metsuke 0.1.1

metsuke 目付 — the typed review surface of a code forge: read what awaits your judgment (pull requests, diffs, review threads) and record the verdict. Mockable Forge/ForgeReview seams over a `gh` backend; no merge, no close, no push.
Documentation
# 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