Metadata-Version: 2.4
Name: review-studio
Version: 0.2.0
Summary: Local-first repository review dashboard
Project-URL: Homepage, https://github.com/Hany-R-Mahmoud/review-studio
Project-URL: Repository, https://github.com/Hany-R-Mahmoud/review-studio
Project-URL: Issues, https://github.com/Hany-R-Mahmoud/review-studio/issues
Author: Hany Mahmoud
License: MIT License
        
        Copyright (c) 2026 Hany Mahmoud
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.13
Requires-Dist: aiosqlite>=0.21
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: fastapi>=0.116
Requires-Dist: keyring>=25.6
Requires-Dist: orjson>=3.11
Requires-Dist: platformdirs>=4.4
Requires-Dist: pydantic-settings>=2.10
Requires-Dist: sqlalchemy[asyncio]>=2.0
Requires-Dist: typer>=0.16
Requires-Dist: uvicorn[standard]>=0.35
Description-Content-Type: text/markdown

# Review Studio

Review Studio is a local-first repository review dashboard. It inspects a selected Git repository, keeps evidence revision-bound, and presents deterministic review results through a private local interface.

It is a desktop-style local tool, not a hosted website: the service binds to `127.0.0.1`, and the dashboard is opened in your browser only on your own machine. Review Studio does not submit GitHub reviews or modify repository source files. Review artifacts can be exported as local Markdown, JSON, or self-contained HTML.

## Install the published package

Requirements: Python 3.13 or newer and [`uv`](https://docs.astral.sh/uv/).

```sh
uv tool install review-studio
cd /path/to/your/repository
review-studio
```

The published package includes the dashboard, so Bun is not required for normal use. Review Studio opens the dashboard at a loopback address such as `http://127.0.0.1:3000`. If that port is busy, it selects the next available loopback port.

Useful options:

```sh
review-studio --help
review-studio --workspace /path/to/your/repository --no-open
review-studio --port 3012
```

`--workspace` selects the repository to inspect; when omitted, Review Studio uses the current directory. `--no-open` starts the local service without opening a browser window. `--port` requests a loopback HTTP port between 1 and 65,535.

## What it does

Review Studio provides bounded actions for repository evidence, including local change analysis, testing and coverage analysis, runtime-log diagnosis, dependency and documentation scans, security review, type analysis, and a full review flow. Actions stop with a specific `Blocked` result when required evidence is missing instead of inventing a result.

Deterministic handlers run first and remain authoritative. AI is optional and must be enabled per action. Before a provider request, **Preview remote context** shows the eligible files, evidence classes, estimated size, destination host, redaction count, truncation state, and digest. A workspace change after preview invalidates the remote call and preserves the deterministic result.

Provider credentials are optional. Review Studio supports OpenAI, Anthropic, and OpenAI-compatible providers. On macOS, credentials are stored in the local Keychain rather than returned to the browser or written to SQLite. Provider failure, rate limiting, malformed output, or missing evidence leaves the local result available and marked partial or unavailable.

The GitHub read adapter is opt-in and requires authenticated `gh` plus `REVIEW_STUDIO_ENABLE_NETWORK=1`. It reads PR metadata and a bounded remote patch, including changed paths and added/deleted line evidence. Start the process with the flag when you want to use **Analyze GitHub PR**:

```sh
REVIEW_STUDIO_ENABLE_NETWORK=1 review-studio --workspace /path/to/your/repository
```

Without that flag, `NETWORK_DISABLED` is an intentional safe block, not a failed analysis. Review Studio does not execute reviewed repository code or AI-generated commands, and it does not automatically commit, push, approve, or write to GitHub.

## Interpreting review output

Review Studio is an evidence workspace, not an autonomous merge approval. **Analyze Current Diff** reports revision-bound diff facts and conservative heuristics; **Run Full Review** combines the available local analyzers but does not replace the repository's tests, lint, type checks, security tooling, or human review. Findings can be inferred or unverified, and a clean result is not proof that a change is safe.

The **Visualize PR Changes** action renders a bounded changed-file topology graph in the dashboard. Directory nodes are connected to the files they contain; link lines are directory-membership evidence, not inferred code dependencies. Node size reflects the file's additions plus deletions. Treat the graph as change navigation evidence, not as a semantic dependency or correctness claim.

The **Analyze GitHub PR** action reads pull-request metadata and a bounded remote patch through the opt-in GitHub CLI adapter—title, state, URL, file count, line counts, changed paths, and changed-line evidence. It does not post comments, create statuses, or write to GitHub. Use **Analyze Current Diff** when reviewing local uncommitted changes.

### Repository review policy

Review Studio accepts an optional repository-owned policy at `.review-studio/config.toml`. Copy the example below and commit the policy when it should apply consistently across contributors:

```sh
cp .review-studio/config.toml.example .review-studio/config.toml
```

The policy supports `review_model`, a separate `triage_model`, reviewer context, ignore globs, and bounded path-scoped rules. Invalid policy fails closed to built-in defaults. Ignored paths are excluded from optional AI context; they are not deleted or modified.

Repeated local reviews persist revision-stable finding threads. Unchanged revisions carry local dismissals or resolutions without another AI request. A changed revision reopens previously triaged findings so an old dismissal cannot silently suppress new evidence. This is local triage only; GitHub conversations and inline comments are not yet connected.

For a review-ready Markdown file, run **Run Full Review**, **Generate PR Summary**, or **Create Review File**, open the completed job, and use the artifact ledger's **Download** action. Full Review now creates its evidence-linked Markdown artifact automatically; the summary and explicit review-file actions remain available for narrower outputs. The deterministic output uses bounded local evidence only. If AI is explicitly enabled, previewed, and successfully run, Generate PR Summary also creates a separate AI-enriched Markdown artifact with the provider, model, context digest, and unverified AI findings. To place a copy in the repository, open a completed local review and explicitly choose **Save copy to workspace**.

## Run from a source checkout

Requirements: Bun, Python 3.13 or newer, and `uv`.

```sh
bun install --frozen-lockfile
bun run build
uv lock --check
uv sync --frozen
uv run review-studio
```

This builds the dashboard, installs the locked Python environment, starts the loopback-only backend, and opens the local interface. For a different port or no browser window, pass the CLI options through the backend command:

```sh
uv run review-studio --no-open --port 3012
```

To install the checkout as an editable command during development:

```sh
bun run build
uv tool install --editable .
review-studio
```

## Local data and review files

Review Studio stores its local application database and generated artifacts under the platform user-data directory. Generated Markdown is available from the completed job's artifact ledger: **Run Full Review** creates a revision-bound evidence-linked review artifact automatically; **Generate PR Summary** creates a deterministic summary artifact and, only after a successful opted-in AI pass, a separate AI-enriched artifact. **Create Review File** creates an editable evidence-linked review artifact using the review template described below. Use the download action in the job detail view to retrieve either file. Generated repository output such as `.next`, `node_modules`, and build directories is excluded from source evidence, while coverage reports remain available to the coverage analyzer.

### Review file quality and template

The review file is rendered by `review_studio/artifacts.py` and includes the revision, worktree fingerprint, summary, active findings, evidence locations, severity, confidence, verification state, rule IDs, bounded code snippets where available, validation hints, impact, recommendations, known unknowns, and provenance. It is a local Markdown evidence packet—not a GitHub approval, SARIF report, or proof that the change is safe. Findings from deterministic analyzers are conservative but can be incomplete; AI findings are explicitly marked unverified. The file records the AI provider and model when an AI pass actually ran. Saving an explicit workspace copy does not change the review fingerprint; later source changes still mark the review stale.

AI is never implicit: the user must enable it for that action, preview the exact redacted context, and run with the matching context digest. The deterministic handler runs first. If the provider is unavailable, over budget, stale, or returns invalid output, Review Studio keeps the deterministic result and marks the AI step unavailable or partial. Provider/model and usage metadata are stored in the local usage ledger; credentials are kept in the macOS Keychain and are not written to the review file or database.

An optional workspace copy of a completed review is written under `.review-studio/reviews/` when you explicitly choose **Save copy to workspace**. It is visible in Git status so it can be reviewed before sharing. The actions do not silently write files into the repository.

Only one Review Studio process should use the local application database at a time. If an action reports that the database is busy, close the other Review Studio process and retry; the API returns an actionable `503` response instead of hiding this condition behind a generic server error.

## Verify changes

```sh
bun run build
uv lock --check
uv sync --frozen
bun run check
```

The test suite covers the API, action contracts, built dashboard, persisted job and review state, provider-secret isolation, staleness, artifact containment, remote-context preview invalidation, bounded GitHub patch parsing, repository review policy, revision-stable triage, provider fallback, budgets, AI-output validation, AST analysis, redaction, and optional-input paths.

The CodeCanary parity assessment and current limitations live in [`docs/codecanary-parity.md`](docs/codecanary-parity.md).

## Release a new version

Merges to `main` do not publish a package. Releases are intentional: use the version helper, review the diff, commit it, and run the manual GitHub Actions workflow. The complete TestPyPI-first procedure is in [`docs/releasing.md`](docs/releasing.md).

```sh
uv run scripts/release_version.py patch --dry-run
uv run scripts/release_version.py patch
```

The helper updates `pyproject.toml` and regenerates `uv.lock`. It accepts `patch`, `minor`, `major`, or an explicit `MAJOR.MINOR.PATCH` version. It never commits, tags, pushes, or publishes.

Release notes live in [`CHANGELOG.md`](CHANGELOG.md). Security reports should follow [`SECURITY.md`](SECURITY.md).

## License

Review Studio is distributed under the [MIT License](LICENSE).
