Crate toolpath_github

Expand description

§toolpath-github

Derive Toolpath provenance documents from GitHub pull requests.

A pull request captures more than code changes — reviews, inline comments, CI checks, and discussion all contribute to the final artifact. This crate maps the full PR lifecycle into a single Toolpath Path where every event becomes a Step in the provenance DAG.

§Overview

Uses the GitHub REST API. Every PR event type becomes a Step with typed actors and artifact changes. Commits carry code diffs; reviews and comments are changes to review:// artifacts; CI checks are changes to ci:// artifacts.

§Usage

use toolpath_github::{derive_pull_request, resolve_token, DeriveConfig};

let token = resolve_token()?;
let config = DeriveConfig {
    token,
    include_ci: true,
    include_comments: true,
    ..Default::default()
};

let path = derive_pull_request("owner", "repo", 42, &config)?;

§Artifact URI scheme

Artifact type	URI pattern	Example
Source file	bare path (relative to base)	`src/main.rs`
Review comment thread	`review://{file}#L{line}`	`review://src/main.rs#L42`
PR conversation	`review://conversation`	`review://conversation`
Review decision	`review://decision`	`review://decision`
CI check result	`ci://checks/{name}`	`ci://checks/build`

The review:// and ci:// schemes are platform-agnostic — they generalize to GitLab MRs, Gerrit, Phabricator, etc.

§Mapping

GitHub concept	Toolpath type	Details
Pull request	Path	id: `pr-{number}`
Commit	Step	actor: `human:{login}`, per-file raw diffs
Review comment	Step	artifact: `review://{path}#L{line}`
PR comment	Step	artifact: `review://conversation`
Review (approve/reject)	Step	artifact: `review://decision`
CI check run	Step	actor: `ci:{app}`, artifact: `ci://checks/{name}`

§API

Function	Description
`resolve_token()`	Resolve GitHub token from `GITHUB_TOKEN` or `gh auth token`
`derive_pull_request(owner, repo, pr, config)`	Derive a Path from a PR
`list_pull_requests(owner, repo, config)`	List PRs with summary info
`extract_issue_refs(body)`	Parse “Fixes #N” / “Closes #N” from text

§CLI

# Derive a Toolpath document from a GitHub PR
path derive github --repo owner/repo --pr 42 --pretty

# Without CI checks or comments
path derive github --repo owner/repo --pr 42 --no-ci --no-comments

# List pull requests
path list github --repo owner/repo --json

§Part of Toolpath

This crate is part of the Toolpath workspace. See also:

toolpath – core types and query API
toolpath-git – derive from git repository history
toolpath-claude – derive from Claude conversations
toolpath-dot – Graphviz DOT rendering
toolpath-cli – unified CLI (cargo install toolpath-cli)
RFC – full format specification

Structs§

DeriveConfig: Configuration for deriving Toolpath documents from a GitHub pull request.
PrUrl: Parsed components of a GitHub PR URL.
PullRequestInfo: Summary information about a pull request.

Functions§

derive_pull_request: Derive a Toolpath Path from a GitHub pull request.
extract_issue_refs: Extract issue references from PR body text.
list_pull_requests: List open pull requests for a repository.
parse_pr_url: Parse a GitHub PR URL into its components.
resolve_token: Resolve a GitHub API token.