Skip to main content

Crate metsuke

Crate metsuke 

Source
Expand description

§metsuke (目付) — the typed review surface of a code forge

Metsuke were the Edo inspectorate: officials whose whole job was to look closely at what was proposed and record a finding. That is this crate — read what awaits your judgment on a code forge, and record the verdict.

§What it is, stated narrowly on purpose

This is not “the fleet’s GitHub client”, and the distinction is load-bearing. A 2026-08-03 survey of pleme-io found ~50 files across ~25 repos independently reaching GitHub, through three different mechanisms (octocrab at five versions, raw HTTP over three different stacks, and gh shell-outs). “Get a commit sha for a ref” alone is implemented at least six times. Consolidating that is a real job and a different one; a crate that claimed both would grow into an everything-client and consolidate neither.

So metsuke owns exactly the surface that survey found absent fleet-wide:

operationbefore
get a PR’s diff / changed filesnowhere
list review threads / commentsnowhere
post a review commentnowhere
approvenowhere
request changesnowhere

Listing and detail are here too, because a review surface that cannot find what to review is not one. Everything else — repo enumeration, file contents, commit resolution, PR creation — is deliberately out of scope and stays where it is.

§Shape

  • Forge reads. ForgeReview writes, and 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. Note what neither trait has: no merge, no close, no push. A reviewer reviews; the absence is the primitive.
  • GhForge is the shipped backend, over gh. MockForge answers from canned data and records what it was asked to submit.
  • Diff text is passed through verbatim. Parsing and rendering it belongs to egaku::chigai and egaku::DiffView, which already own it; a second diff parser in the client would be the duplication this crate exists to remove.

§Tier honesty

SHIPPED and PROVEN LIVE (2026-08-03). pending-metsuke: live-read is CLOSED. The whole chain ran against real GitHub: a search returned 10 typed rows, all four Involvement lanes were accepted by gh as qualifiers, a real PR yielded 11 changed files whose patches are genuine unified-diff text, and its review comments parsed. See tests/live_read.rs (#[ignore]d — it needs network and a credential).

That measurement is the point of the row, not a formality: every parser here was written against GitHub’s documented shapes and pinned with hand-written JSON, which proves self-consistency and nothing about what GitHub sends. The fleet has been bitten by exactly that gap — banken’s --features live compiled clean for weeks, then aborted on its first real call.

Two things the live run found that no fixture could have: --involves=@me being a valid gh flag is a fact about the CLI, not about these types; and a hardcoded PR number eventually points at something deleted, so the files test now chains off a live search rather than skipping-and-passing.

Still 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.

§Example

use metsuke::{Forge, Involvement, MockForge};

let forge = MockForge::new();
let waiting = forge.search(Involvement::ReviewRequested, 25).unwrap();
assert!(waiting.is_empty());

Re-exports§

pub use forge::Forge;
pub use forge::ForgeReview;
pub use forge::MockForge;
pub use gh::GhForge;
pub use gh::GhRunner;
pub use gh::RealGh;
pub use types::FilePatch;
pub use types::ForgeError;
pub use types::Involvement;
pub use types::PrNumber;
pub use types::PrState;
pub use types::PrSummary;
pub use types::RepoId;
pub use types::Result;
pub use types::ReviewComment;
pub use types::Verdict;

Modules§

forge
The seam: what a forge can be asked, and a mock that answers.
gh
The gh backend: argv construction and answer parsing, kept apart from the process that runs them.
types
The typed vocabulary of a code-forge review.