revdep

package
v0.23.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 13, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

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

View Source
const DefaultIndexURL = "https://index.crates.io/"

DefaultIndexURL is the crates.io sparse-index endpoint.

Variables

View Source
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

type Boundary struct {
	Crate string
	From  string
	To    string
}

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

func NewClient(base string, hc *http.Client) *Client

NewClient builds a sparse-index client rooted at base. A nil http client defaults to a 30s-timeout client.

func (*Client) Fetch

func (c *Client) Fetch(ctx context.Context, name string) ([]IndexVersion, error)

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

type DirectEdit struct {
	Member     string
	Dependency string
	MinVersion string
}

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.

func Calculate

func Calculate(ctx context.Context, crate, targetVersion string, opts Options) (*Plan, error)

Calculate walks the inverted dependency tree for crate and computes the direct-dependency edits and precise boundary pins needed to make targetVersion (a floor, i.e. ">= target") reachable. An empty, non-error Plan means the crate already satisfies the floor.

func (*Plan) Empty

func (p *Plan) Empty() bool

Empty reports whether the plan requires no changes (the target is already satisfied, or nothing needs upgrading).

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.

func ParseTree

func ParseTree(text string) (*TreeNode, error)

ParseTree parses `cargo tree` output. It supports both the "--prefix depth" format (each line prefixed with a numeric depth) and the ASCII box-drawing format, so a hand-pasted tree can be fed in as well.

type TreeProvider

type TreeProvider func(ctx context.Context, crate string) (string, error)

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

func ParseVersion(s string) (Version, error)

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.

func (Version) Compare

func (v Version) Compare(o Version) int

Compare returns -1, 0 or 1 following semver ordering (release > pre-release).

func (Version) String

func (v Version) String() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL