# metsuke (目付)
**The typed review surface of a code forge.** Read what awaits your judgment —
pull requests, diffs, review threads — and record the verdict.
*Metsuke* were the Edo inspectorate: officials whose whole job was to look
closely at what was proposed and record a finding.
```rust
use metsuke::{Forge, ForgeReview, GhForge, Involvement, RealGh, Verdict};
let forge = GhForge::new(RealGh);
// What is waiting on you.
for pr in forge.search(Involvement::ReviewRequested, 25)? {
println!("{} {} — {}", pr.repo, pr.number, pr.title);
}
// What changed. `patch` is the forge's own unified diff, verbatim.
let repo = metsuke::RepoId::parse("pleme-io/metsuke")?;
for f in forge.files(&repo, metsuke::PrNumber(12))? {
println!("{} +{} -{}", f.path, f.additions, f.deletions);
}
// The verdict.
forge.submit_review(&repo, metsuke::PrNumber(12), &Verdict::Approve("lgtm".into()))?;
```
## Scope — narrow on purpose
This is **not** a general GitHub client. A survey of the pleme-io fleet
(2026-08-03) found ~50 files across ~25 repos independently reaching GitHub
through three mechanisms — octocrab at five different versions, raw HTTP over
three stacks, and `gh` shell-outs. "Get a commit sha for a ref" alone was
implemented at least six times. Consolidating *that* is a real job and a
different one; a crate claiming both would grow into an everything-client and
consolidate neither.
metsuke owns exactly what that survey found **absent fleet-wide**: a PR's
diff, its review threads, and the three review verbs. Listing and detail come
along because a review surface that cannot find what to review is not one.
Repo enumeration, file contents, commit resolution, and PR *creation* are out
of scope and stay where they are.
## Design
- **`Forge` reads, `ForgeReview` writes**, and the write trait holds exactly
one method. A read-only consumer takes `&impl Forge` and has no way to
submit a verdict — not by convention, but because the method is not on the
trait it holds.
- **No `merge`, no `close`, no `push`.** A reviewer reviews. The absence is
the primitive: there is no place to put a forge-mutation API, so one does
not accumulate.
- **`Verdict::is_binding()`** distinguishes a comment from an approval or a
request-for-changes, so a UI knows which ones to confirm first. The crate
does not confirm on your behalf — a library that silently declines to do
what it was asked is worse than one that does it.
- **Diff text passes through verbatim.** Parsing and rendering belong to
`egaku::chigai` and `egaku::DiffView`, which already own them.
- **Argv construction and answer parsing are pure functions**, separate from
the process that runs them. Both are fully tested with no subprocess and no
network; the only untested-without-a-network surface is the four lines that
spawn.
- **Honest optionality.** A binary file has `patch: None`, not `Some("")`. An
outdated review thread keeps `line: None` rather than being defaulted to 0,
which would point a reader at the wrong place with no hint it was wrong. A
PR whose repository cannot be determined is dropped, not defaulted — every
action on it would target the wrong repo.
## Why `gh` and not an HTTP client
`gh` already solves the part nobody enjoys: credential discovery across
keyring, config file, `GH_TOKEN`, `GITHUB_TOKEN`, enterprise hosts, and App
installations. An HTTP backend that ignores all that works on your machine and
fails in CI. It is still a *backend* behind the `Forge` trait — an HTTP one can
be added beside it without a consumer noticing.
## Tier honesty
**Shipped and proven live (2026-08-03).** 19 unit tests with no network, plus
4 `#[ignore]`d live tests that ran against real GitHub: a search returned 10
typed rows, all four involvement lanes were accepted by `gh`, a real PR yielded
11 changed files with genuine unified-diff patches, and its review comments
parsed. `pending-metsuke: live-read` is **closed**.
```bash
cargo test --test live_read -- --ignored --nocapture
```
**Not exercised live: the write half.** `submit_review` posts a real review to
a real PR, so it is proven only against `MockForge` — nobody should approve
someone's pull request to satisfy a test suite. `pending-metsuke: live-write`.
## License
MIT