Metadata-Version: 2.3
Name: takopi-review
Version: 0.1.7
Summary: Review orchestration plugin for Takopi.
Keywords: takopi,review,plugin,code-review
Author: takopi contributors
License: MIT License
         
         Copyright (c) takopi contributors
         
         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.
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Dist: takopi>=0.22,<0.23
Requires-Python: >=3.14
Project-URL: Homepage, https://takopi.dev
Description-Content-Type: text/markdown

# takopi-review

multi-review orchestration plugin for takopi.

`takopi-review` runs multiple review agents over the same diff bundle, normalizes
their findings into one schema, deduplicates overlap, and produces a single
report you can act on. It keeps raw reviewer output for audit, but everything
downstream uses the same provider-agnostic finding shape.

## shipped now

phase 1 of the review pipeline is implemented here:

- natural-language `/review <request>` runs, including reply-to-snippet reviews
- repo-aware PR review requests such as `/review this pr 123 in this repo owner/repo`
- working-tree diff requests such as `/review the working tree diff`
- commit review requests such as `/review commit abc1234`
- normalized provider-agnostic findings
- consolidated markdown reports with audit artifacts
- lead reviewer validation, dedupe, and prioritization
- final review message inherits the lead reviewer session metadata when available

## how it works

the plugin runs in four stages:

1. collect the review target, diff or source content, changed files when
   available, inferred language/test surface, and workspace instructions
2. run the repo-owned specialist reviewer roles in parallel against the same bundle
3. run a final lead reviewer that validates the specialist findings, merges
   overlap, ranks the final list, and emits the grounded output
4. persist the consolidated report and raw reviewer artifacts for audit

## requirements

- python 3.14+
- takopi installed
- `codex` available in your takopi setup
- `gh` installed if you want `/review pr ...`

## install

```sh
uv tool install -U takopi --with takopi-review
```

or install into the same environment as takopi:

```sh
pip install -U takopi-review
```

enable it:

```toml
[plugins]
enabled = ["takopi-review"]
```

## commands

review a freeform request, optionally by replying to a pasted snippet or message:

```text
/review python auth middleware in this pasted snippet
/review typescript react component for accessibility --focus ui
```

review the current workspace diff:

```text
/review the working tree diff
/review the current diff --focus security --focus tests
```

review a pull request, including one from another repo:

```text
/review this pr 123
/review this pr 123 in this repo richardliang/takopi-review --focus performance
/review https://github.com/acme/repo/pull/123
```

review a commit:

```text
/review commit abc1234
```

reviewer roles are now fixed in the repo/plugin and are no longer user-settable
from the command line. the shipped pipeline runs these specialist lanes by
default, on `codex` only:

- `security-best-practices`
- `typechecker`
- `correctness-simplicity`
- `tests`
- `boundary-regressions`

the `typechecker` lane stays enabled for every review because the intended repo
set is typed by default.

when the changed files include a committed spec document such as a PRD, spec,
requirements doc, design doc, or RFC in a text format, the pipeline also adds:

- `spec-reviewer`

when the bundle looks like React or Next.js code, the pipeline also adds:

- `react-vercel`

before the lead pass, the pipeline also runs one broad
`code-review-excellence-codex` sweep lane.

after those pre-lead passes finish, a single final `code-review-excellence`
lead reviewer runs on `codex`, validates whether the reviewer findings are
actually grounded, merges duplicates, and ranks the final report. the lead lane
is explicitly single-engine so the final emitted message has one canonical
session to inherit.

the `security-best-practices` lane is backed by the repo-local skill corpus in
`src/takopi_review/review_skills.py` and uses the bundled language- and
framework-specific references when the bundle matches supported stacks.

the final lead lane is backed by the same repo-local skill corpus, so the
adjudication stage uses explicit code-review principles rather than a bespoke
repo-local reviewer persona.

the repo vendors one shared skill corpus for the shipped review lanes. the
reviewer prompt loader does not depend on external skill installs for review
prompt enrichment.

all `/review` commands go through the same parser. the plugin uses an LLM
pre-pass to infer the review target, repo hint, and primary language signal
from the text after `/review` and any replied content, then injects that signal
into the reviewer prompts.

## outputs

review artifacts are written under `.takopi/review/` by default:

```text
.takopi/review/
  latest.json
  <run-id>/
    bundle.json
    report.json
    report.md
    raw/
      security-best-practices-codex.txt
      typechecker-codex.txt
      correctness-simplicity-codex.txt
      tests-codex.txt
      boundary-regressions-codex.txt
      spec-reviewer-codex.txt
      react-vercel-codex.txt
      code-review-excellence-codex.txt
      code-review-excellence-lead-codex.txt
```

the markdown review report includes:

- a consolidated findings table
- a terse final summary from the lead reviewer
- an agreement matrix by specialist reviewer
- missing reviewers that were skipped for the bundle
- recommended fix order
- per-finding reviewed code, suggested fix, and agent prompt
- testing gaps
- reviewer execution errors, if any

## finding schema

all reviewer output is normalized into this shape before consolidation:

```json
{
  "reviewer": "security-best-practices-codex",
  "title": "Missing authorization check",
  "priority": 1,
  "confidence": 0.84,
  "file": "src/example.py",
  "start_line": 42,
  "end_line": 45,
  "summary": "Route allows any Slack user to trigger destructive actions.",
  "suggested_fix": "Check allowed_user_ids before dispatch.",
  "reviewed_code": "delete route still succeeds for unauthorized users.",
  "agent_prompt": "Update src/example.py so unauthorized users are rejected before dispatch and add regression coverage for the denied path."
}
```

## config

```toml
[plugins.review]
timeout_s = 900
max_parallel_reviews = 8
require_repo = true
post_github_comments = true
report_dir = ".takopi/review"
```

reports and raw reviewer outputs are stored under `report_dir` inside the repo.
set `require_repo = false` to allow natural-language snippet reviews outside a
git repo; repo-targeted PR reviews can already run without a local checkout when
the command names the repo explicitly.
when `post_github_comments = true`, PR reviews post the consolidated findings
directly to the GitHub PR thread. the comment body is compacted and split across
multiple PR comments when needed to stay under GitHub size limits, and the Slack
reply is reduced to `job done`.

`plugins.review.reviewers`, `plugins.review.default_fixer`,
`plugins.review.auto_fix`, and `/review fix` were removed in the hard cutover.
reviewer selection now belongs to the repo-owned orchestration pipeline, not
the caller.

## development

install the locked dev environment:

```sh
uv sync --frozen --group dev
```

run the same checks as CI:

```sh
uv run --no-sync ruff check
uv run --no-sync pytest -q
```

build the package locally:

```sh
uv build
```

## release

ci runs on pushes to `main` and pull requests. publishing is wired through
github actions on tags matching `v*`.

once PyPI trusted publishing is configured, a release is:

```sh
git tag v0.1.0
git push origin main --tags
```
