Documentation
¶
Overview ¶
SPDX-License-Identifier: MIT
SPDX-License-Identifier: MIT Package ghclient wraps the go-github client with the commit-discovery strategies the tool needs and normalizes results into model types.
SPDX-License-Identifier: MIT
Index ¶
- type Client
- func (c *Client) Collect(ctx context.Context, q model.Query) (model.Result, error)
- func (c *Client) CollectActivity(ctx context.Context, q model.ActivityQuery) (model.ActivityResult, error)
- func (c *Client) Cost() model.CostReport
- func (c *Client) EstimateActivity(ctx context.Context, q model.ActivityQuery) (model.CostReport, error)
- type Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client retrieves commits from GitHub for an author over a time window.
func New ¶
New builds a Client. token may be empty (unauthenticated, heavily rate limited). baseURL, when set, targets a GitHub Enterprise instance and must be the API root (e.g. "https://ghe.example.com/api/v3/"). perPage is clamped to the API's 1-100 range.
Options are applied before the HTTP client is constructed, because WithRequestBudget installs a transport that everything else must be layered on top of.
func (*Client) CollectActivity ¶ added in v1.1.0
func (c *Client) CollectActivity(ctx context.Context, q model.ActivityQuery) (model.ActivityResult, error)
CollectActivity gathers a repository's activity for a window: the commits, the aggregate change set between the window's boundary states, the correlations between them, and what the whole thing cost.
It returns a populated ActivityResult on every non-fatal path — budget stops, quota exhaustion, and ancestry divergence all produce a result plus a disclosure. The error return is reserved for failures that occur before evidence gathering begins, because discarding gathered evidence to report a bound is the blindness Constitution VI forbids.
func (*Client) Cost ¶ added in v1.1.0
func (c *Client) Cost() model.CostReport
Cost reports what this client has consumed and the latest quota observation. It returns a zero report when the client was built without WithRequestBudget, and is safe to call at any point including after a failure — a query that stopped early must still report what it spent.
func (*Client) EstimateActivity ¶ added in v1.1.0
func (c *Client) EstimateActivity(ctx context.Context, q model.ActivityQuery) (model.CostReport, error)
EstimateActivity reports the projected cost of a query without gathering its evidence.
It issues exactly one probe: a per_page=1 list-commits request whose Link header yields LastPage, which with a page size of 1 *is* the exact number of commits in the window (research R4). That turns the estimate from a heuristic into arithmetic. The probe itself is counted in the reported cost — hiding it would make the accounting dishonest about its own overhead.
The probe gathers no evidence: the single commit it returns is discarded and only the Link header is read.
type Option ¶ added in v1.1.0
type Option func(*Client)
Option configures a Client at construction time. New takes options variadically, so every existing three-argument call site stays source-compatible.
func WithRequestBudget ¶ added in v1.1.0
WithRequestBudget caps the provider requests the client may consume and enables cost accounting.
A ceiling of 0 disables the cap but still accounts: accounting is never optional, only enforcement is, so an intentional uncapped run can still report what it spent. Negative ceilings are treated as 0.
Enforcement happens in the transport, which means it covers every request the client makes — pagination and retries included — without any call site needing to know about it.
Source Files