bevy_lint/lints/nursery/duplicate_bevy_dependencies.rs
1//! Checks for multiple versions of the `bevy` crate in your project's dependencies.
2//!
3//! This lint will prevent you from accidentally using multiple versions of the Bevy game engine at
4//! the same time by scanning your dependency tree for the `bevy` crate. If your project or its
5//! dependencies use different versions of `bevy`, this lint will emit a warning.
6//!
7//! You may also be interested in [`cargo-deny`], which can detect duplicate dependencies as well,
8//! and is far more powerful and configurable.
9//!
10//! [`cargo-deny`]: https://github.com/EmbarkStudios/cargo-deny
11//!
12//! # Motivation
13//!
14//! Cargo allows there to be multiple major versions of a crate in your project's dependency
15//! tree[^semver-compatibility]. Although the crates and their types are _named_ the same, they are
16//! treated as distinct by the compiler. This can lead to confusing error messages that only appear
17//! if you try to mix the types from the two versions of the crate.
18//!
19//! With Bevy, these errors become particularly easy to encounter when you add a plugin that pulls
20//! in a different version of the Bevy engine. (This isn't immediately obvious, however, unless you
21//! look at `Cargo.lock` or the plugin's engine compatibility table.)
22//!
23//! [^semver-compatibility]: The rules for dependency unification and duplication are specified
24//! [here](https://doc.rust-lang.org/cargo/reference/resolver.html#semver-compatibility).
25//!
26//! # Known Issues
27//!
28//! This lint only works if a specific version of `bevy` is declared. If a version range is
29//! specified, this lint will be skipped. For example:
30//!
31//! ```toml
32//! [dependencies]
33//! # This will not be linted, since it is a version range.
34//! bevy = ">=0.15"
35//! ```
36//!
37//! # Example
38//!
39//! ```toml
40//! [package]
41//! name = "foo"
42//! edition = "2024"
43//!
44//! [dependencies]
45//! bevy = "0.15"
46//! # This depends on Bevy 0.14, not 0.15! This will cause duplicate versions of the engine.
47//! leafwing-input-manager = "0.15"
48//! ```
49//!
50//! Use instead:
51//!
52//! ```toml
53//! [package]
54//! name = "foo"
55//! edition = "2024"
56//!
57//! [dependencies]
58//! bevy = "0.15"
59//! # Update to a newer version of the plugin, which supports Bevy 0.15.
60//! leafwing-input-manager = "0.16"
61//! ```
62
63use std::{collections::BTreeMap, ops::Range, path::Path, str::FromStr, sync::Arc};
64
65use crate::declare_bevy_lint;
66use cargo_metadata::{
67 Metadata, Resolve,
68 semver::{Version, VersionReq},
69};
70use clippy_utils::{
71 diagnostics::{span_lint, span_lint_and_then},
72 find_crates,
73};
74use rustc_hir::def_id::LOCAL_CRATE;
75use rustc_lint::LateContext;
76use rustc_span::{BytePos, Pos, SourceFile, Span, Symbol, SyntaxContext};
77use serde::Deserialize;
78use toml::Spanned;
79
80declare_bevy_lint! {
81 pub DUPLICATE_BEVY_DEPENDENCIES,
82 super::NURSERY,
83 "multiple versions of the `bevy` crate found",
84 @crate_level_only = true,
85}
86
87#[derive(Deserialize, Debug)]
88struct CargoToml {
89 dependencies: BTreeMap<Spanned<String>, Spanned<toml::Value>>,
90}
91
92fn toml_span(range: Range<usize>, file: &SourceFile) -> Span {
93 Span::new(
94 file.start_pos + BytePos::from_usize(range.start),
95 file.start_pos + BytePos::from_usize(range.end),
96 SyntaxContext::root(),
97 None,
98 )
99}
100
101pub fn check(cx: &LateContext<'_>, metadata: &Metadata, bevy_symbol: Symbol) {
102 // no reason to continue the check if there is only one instance of `bevy` required
103 if find_crates(cx.tcx, bevy_symbol).len() == 1 {
104 return;
105 }
106
107 // Load the `Cargo.toml` into the `SourceMap` this is necessary to get the `Span` of the
108 // `Cargo.toml` file.
109 if let Ok(file) = cx.tcx.sess.source_map().load_file(Path::new("Cargo.toml"))
110 && let Some(src) = file.src.as_deref()
111 // Parse the `Cargo.toml` file into a `CargoToml` struct, this helps getting the correct span and not just
112 // the root span of the `Cargo.toml` file.
113 && let Ok(cargo_toml) = toml::from_str::<CargoToml>(src)
114 {
115 let local_name = cx.tcx.crate_name(LOCAL_CRATE);
116
117 // get the package name and the corresponding version of `bevy` that they depend on
118 let mut bevy_dependents = BTreeMap::default();
119 for package in &metadata.packages {
120 for dependency in &package.dependencies {
121 if dependency.name.as_str() == "bevy"
122 && package.name.as_str() != local_name.as_str()
123 {
124 bevy_dependents.insert(package.name.as_str(), dependency.req.clone());
125 }
126 }
127 }
128
129 // If `bevy` is listed as a direct dependency, use its version as the target version for all
130 // other crates, and check for any dependents that use a different version.
131 // If `bevy` is not listed as a direct dependency, check if multiple versions of `bevy` are
132 // resolved. If so, report a single lint error.
133 match cargo_toml.dependencies.get("bevy") {
134 Some(bevy_cargo) => {
135 lint_with_target_version(cx, &cargo_toml, &file, bevy_cargo, &bevy_dependents);
136 }
137
138 None => {
139 if let Some(resolve) = &metadata.resolve {
140 minimal_lint(cx, &bevy_dependents, resolve);
141 };
142 }
143 };
144 }
145}
146
147fn lint_with_target_version(
148 cx: &LateContext<'_>,
149 cargo_toml: &CargoToml,
150 file: &Arc<SourceFile>,
151 bevy_cargo: &Spanned<toml::Value>,
152 bevy_dependents: &BTreeMap<&str, VersionReq>,
153) {
154 // Semver only supports checking if a given `VersionReq` matches a `Version` and not if two
155 // `VersionReq` can successfully resolve to one `Version`. Therefore we try to parse the
156 // `Version` from the `bevy` dependency in the `Cargo.toml` file. This only works if a
157 // single version of `bevy` is specified and not a range.
158 let Ok(target_version) = get_version_from_toml(bevy_cargo.as_ref()) else {
159 return;
160 };
161
162 let bevy_cargo_toml_span = toml_span(bevy_cargo.span(), file);
163
164 let mismatching_dependencies = bevy_dependents
165 .iter()
166 .filter(|dependency| !dependency.1.matches(&target_version));
167
168 for mismatching_dependency in mismatching_dependencies {
169 if let Some(cargo_toml_reference) = cargo_toml.dependencies.get(*mismatching_dependency.0) {
170 span_lint_and_then(
171 cx,
172 DUPLICATE_BEVY_DEPENDENCIES.lint,
173 toml_span(cargo_toml_reference.span(), file),
174 DUPLICATE_BEVY_DEPENDENCIES.lint.desc,
175 |diag| {
176 diag.span_help(
177 bevy_cargo_toml_span,
178 format!("expected all crates to use `bevy` {target_version}, but `{}` uses `bevy` {}", mismatching_dependency.0, mismatching_dependency.1),
179 );
180 },
181 );
182 }
183 }
184}
185
186fn minimal_lint(
187 cx: &LateContext<'_>,
188 bevy_dependents: &BTreeMap<&str, VersionReq>,
189 resolved: &Resolve,
190) {
191 // Examples of the underlying string representation of resolved crates
192 // "id": "file:///path/to/my-package#0.1.0",
193 // "id": "registry+https://github.com/rust-lang/crates.io-index#bevy@0.9.1",
194 let mut resolved_bevy_versions: Vec<&str> = resolved
195 .nodes
196 .iter()
197 .filter_map(|node| {
198 // Extract version from local crates
199 if node.id.repr.starts_with("file:///") {
200 return node.id.repr.split('#').nth(1).map(|version| vec![version]);
201 }
202 // Extract versions from external crates
203 if let Some((id, _)) = node.id.repr.split_once('@') {
204 if bevy_dependents
205 .keys()
206 .any(|crate_name| id.ends_with(crate_name))
207 {
208 return Some(
209 node.dependencies
210 .iter()
211 .filter_map(|dep| dep.repr.split_once('@'))
212 .filter_map(|(name, version)| {
213 (name.contains("bevy")).then_some(version)
214 })
215 .collect(),
216 );
217 }
218 }
219
220 None
221 })
222 .flatten()
223 .collect();
224
225 resolved_bevy_versions.sort_unstable();
226 resolved_bevy_versions.dedup();
227
228 if resolved_bevy_versions.len() > 1 {
229 span_lint(
230 cx,
231 DUPLICATE_BEVY_DEPENDENCIES.lint,
232 rustc_span::DUMMY_SP,
233 "found multiple versions of bevy",
234 );
235 }
236}
237
238/// Extracts the `version` field from a [`toml::Value`] and parses it into a [`Version`]
239/// There are two possible formats:
240/// 1. A toml-string `<crate> = <version>`
241/// 2. A toml-table `<crate> = { version = <version> , ... }`
242///
243/// Cargo supports specifying version ranges,
244/// but [`Version::from_str`] can only parse exact versions and not ranges.
245fn get_version_from_toml(table: &toml::Value) -> anyhow::Result<Version> {
246 match table {
247 toml::Value::String(version) => Version::from_str(version).map_err(anyhow::Error::from),
248 toml::Value::Table(table) => table
249 .get("version")
250 .and_then(toml::Value::as_str)
251 .ok_or_else(|| anyhow::anyhow!("The 'version' field is required."))
252 .and_then(|version| Version::from_str(version).map_err(anyhow::Error::from)),
253 _ => Err(anyhow::anyhow!(
254 "Unexpected TOML format: expected a toml-string '<crate> = <version>' or a toml-table with '<crate> = {{ version = <version> }} '"
255 )),
256 }
257}