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
  • Coverage
  • 64.21%
    61 out of 95 items documented1 out of 43 items with examples
  • Size
  • Source code size: 60.6 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 961.7 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 5s Average build duration of successful builds.
  • all releases: 5s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • pleme-io/metsuke
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • drzln

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.

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.

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