guppy

guppy is a Rust library that provides a programmatic interface for tracking and querying Cargo dependency graphs. It parses the output of cargo metadata and presents it as a rich, in-memory graph where every node is a package and every edge is a dependency, giving you a powerful way to reason about a workspace’s dependencies without shelling out and hand-parsing JSON.

The central PackageGraph type supports queries such as finding all transitive dependencies or dependents, filtering by dependency kind or target platform, computing feature sets, and detecting cycles. It powers real-world tooling - including cargo-hakari and the determinator - for workspace optimization and change-impact analysis.

What You Get

• A PackageGraph built from cargo metadata output with typed PackageMetadata access
• Forward and reverse transitive queries to find dependencies and dependents
• Filtering by dependency kind (normal, dev, build) and target platform
• Cargo feature-set resolution and platform-aware analysis
• Cycle detection and lifetime-checked borrowing of graph data

Common Use Cases

• Analyzing which crates a change in a workspace can affect for CI test selection
• Auditing transitive dependencies and their sources across a large workspace
• Computing platform- or feature-specific dependency sets programmatically
• Building custom Cargo tooling that needs a reliable dependency-graph model

Under The Hood

Architecture - The heart of the crate is guppy/src/graph/, where graph_impl.rs builds a PackageGraph on top of a petgraph structure from cargo metadata output (obtained via metadata_command.rs). Query logic is split across query.rs/query_core.rs for transitive traversals, feature/ for Cargo feature resolution, cargo/ for build-simulation queries, and cycles.rs for cycle detection. A 'g lifetime threads borrowed data from the owning PackageGraph through PackageMetadata and related view types, and platform/ handles target-specific evaluation.

Tech Stack - Rust built on cargo_metadata for parsing, petgraph and fixedbitset for graph storage and traversal, camino for UTF-8 paths, semver for version handling, indexmap/ahash for deterministic maps, and target-spec (a sibling crate) for platform expression evaluation.

Code Quality - The crate is well engineered and actively maintained (health score 68), with an extensive test suite: unit tests under src/unit_tests, integration graph-tests, proptest-based helpers, and fixture-driven datatests. Meta/Facebook provenance and downstream tools (cargo-hakari, determinator) exercise it heavily in production.

API Design - The API is powerful but has a real learning curve because it faithfully models Cargo’s complexity (feature unification, dependency kinds, platform conditionals) and uses lifetime parameters to avoid cloning. Once the PackageGraph mental model clicks, queries read declaratively, and the documentation is thorough with clearly named types.