Documentation
¶
Overview ¶
Package revdep computes, for a Rust crate and a target version, the minimum version each reverse dependency must be upgraded to so the target becomes reachable — terminating at the workspace crate whose Cargo.toml must be edited.
It is a copy of the standalone rust-reverse-dependency-calculator, adapted into an importable package with a context-aware crates.io index client and a single Calculate entry point. The manifest-editing half of the original tool is intentionally omitted: omnibump's own appliers perform the Cargo.toml edits.
Index ¶
- Constants
- Variables
- type Boundary
- type Client
- func (c *Client) Fetch(ctx context.Context, name string) ([]IndexVersion, error)
- func (c *Client) MaxVersion(ctx context.Context, crate string, allowPre bool) (Version, bool, error)
- func (c *Client) MinVersionRequiring(ctx context.Context, dependent string, floor Version, depCrate string, ...) (Version, error)
- func (c *Client) VersionsAtLeast(ctx context.Context, crate string, floor Version, allowPre bool) ([]Version, error)
- type DirectEdit
- type Fetcher
- type IndexDep
- type IndexVersion
- type Options
- type Plan
- type Requirement
- type TreeNode
- type TreeProvider
- type Version
Constants ¶
const DefaultIndexURL = "https://index.crates.io/"
DefaultIndexURL is the crates.io sparse-index endpoint.
Variables ¶
var ErrNotFound = errors.New("not found in index")
ErrNotFound indicates a crate is absent from the index, which for our purposes means it is a local/workspace (path) crate rather than a published one.
Functions ¶
This section is empty.
Types ¶
type Boundary ¶
Boundary is a published crate to pin with `cargo update -p Crate@From --precise To`.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client fetches and caches crate metadata from a crates.io-style sparse index.
func NewClient ¶
NewClient builds a sparse-index client rooted at base. A nil http client defaults to a 30s-timeout client.
func (*Client) Fetch ¶
Fetch returns all published versions of a crate, newest last, cached per name.
func (*Client) MaxVersion ¶
func (c *Client) MaxVersion(ctx context.Context, crate string, allowPre bool) (Version, bool, error)
MaxVersion returns the highest non-yanked published version of a crate. The bool is false when the crate has no usable versions.
func (*Client) MinVersionRequiring ¶
func (c *Client) MinVersionRequiring(ctx context.Context, dependent string, floor Version, depCrate string, depFloor Version, acceptable []Version, allowPre bool) (Version, error)
MinVersionRequiring returns the lowest non-yanked version of dependent that is >= floor and whose requirement on depCrate can resolve to at least one of the acceptable depCrate versions.
This is the core step: given that depCrate must resolve to some version in `acceptable` (i.e. >= the child's own minimum), it finds the minimal upgrade of the crate that depends on it. A parent qualifies as soon as it *permits* an acceptable child version, because Cargo resolves to the highest permitted one.
depFloor is depCrate's target version (the line the bumped instance lives in). It disambiguates when a candidate depends on depCrate under multiple renames — see the grouping logic below.
func (*Client) VersionsAtLeast ¶
func (c *Client) VersionsAtLeast(ctx context.Context, crate string, floor Version, allowPre bool) ([]Version, error)
VersionsAtLeast returns all non-yanked published versions of crate that are >= floor, sorted ascending. Pre-releases are excluded unless allowPre is set or the floor is itself a pre-release (see preAllowed).
type DirectEdit ¶
DirectEdit says a workspace member must widen its constraint on Dependency to allow at least MinVersion.
type Fetcher ¶
type Fetcher interface {
MaxVersion(ctx context.Context, crate string, allowPre bool) (Version, bool, error)
VersionsAtLeast(ctx context.Context, crate string, floor Version, allowPre bool) ([]Version, error)
MinVersionRequiring(ctx context.Context, dependent string, floor Version, depCrate string, depFloor Version, acceptable []Version, allowPre bool) (Version, error)
}
Fetcher answers the version queries the walk needs. *Client is the live crates.io-backed implementation; tests inject a stub.
type IndexDep ¶
type IndexDep struct {
Name string `json:"name"` // the (possibly renamed) dependency name
Req string `json:"req"` // Cargo version requirement
Kind string `json:"kind"` // "normal", "build" or "dev" ("" == normal)
Optional bool `json:"optional"` //
Package string `json:"package"` // real crate name when the dep is renamed
}
IndexDep mirrors a dependency entry in a crates.io sparse-index record.
type IndexVersion ¶
type IndexVersion struct {
Name string `json:"name"`
Vers string `json:"vers"`
Deps []IndexDep `json:"deps"`
Yanked bool `json:"yanked"`
}
IndexVersion mirrors a single line of a sparse-index file.
type Options ¶
type Options struct {
// Tree provides the inverted dependency tree for a crate. Required.
Tree TreeProvider
// Index answers version queries. Defaults to a live crates.io client built
// from IndexURL/HTTP when nil.
Index Fetcher
// IndexURL is the sparse-index base URL used when Index is nil.
IndexURL string
// HTTP is the client used when Index is nil.
HTTP *http.Client
// AllowPre considers pre-release versions as upgrade candidates.
AllowPre bool
// WorkspaceMembers names the project's local crates. A crate that is absent
// from the index is only treated as a local (editable) crate when it is a
// known member (or cargo annotated it with a path); this guards crates from
// private registries that merely 404 on crates.io. When nil, any index miss
// is treated as local (the standalone tool's behavior).
WorkspaceMembers map[string]bool
}
Options configures a Calculate run.
type Plan ¶
type Plan struct {
Target string
From string
To string
Edits []DirectEdit
Boundaries []Boundary
}
Plan is the result of Calculate: the direct-dependency manifest edits and the precise version pins needed to make the target reachable.
type Requirement ¶
type Requirement struct {
// contains filtered or unexported fields
}
Requirement is a Cargo version requirement: a set of comparators combined with AND. It implements the subset of Cargo's VersionReq grammar that appears in practice: caret (the default), tilde, wildcard, '=', and the inequality operators, joined by commas.
func ParseRequirement ¶
func ParseRequirement(s string) (Requirement, error)
ParseRequirement parses a full Cargo requirement string (comma-separated).
func (Requirement) Matches ¶
func (r Requirement) Matches(v Version) bool
Matches reports whether v satisfies the requirement, applying Cargo's rule that a pre-release version only matches when a comparator names the same major.minor.patch with its own pre-release tag.
type TreeNode ¶
type TreeNode struct {
Name string
Version string
Path string // local crate directory, when cargo annotates one (path deps)
Children []*TreeNode
}
TreeNode is a node in an inverted dependency tree. In `cargo tree -i` output the root is the queried crate and each child is a crate that depends on it.
type TreeProvider ¶
TreeProvider yields `cargo tree -i <crate> -e normal,build --charset ascii --prefix depth` output rooted in the target workspace. It is injected so the caller controls how cargo is invoked (toolchain, working directory) and tests can feed canned trees.
type Version ¶
type Version struct {
Major, Minor, Patch uint64
Pre string // pre-release, without the leading '-'
}
Version is a semantic version. Build metadata (after '+') is discarded because it does not participate in version comparison.
func ParseVersion ¶
ParseVersion parses a concrete version such as "0.56.0" or "1.2.3-rc.1". A leading 'v' is tolerated. Missing minor/patch components default to 0.