feat(lint): new implicit_minimum_version_req lint

weihanglo · weihanglo · commit 192475a6f547 · 2025-12-08T17:39:43.000-05:00
Add a new `cargo::implicit_minimum_version_req` lint:
Only check if dependency has a single caret requirement.
All other requirements (multiple, tilde, wildcard)
are not linted by this rule, as they usually have significance
on what version fields get specified.

This currently lints only dependencies with no workspace inheritance.
diff --git a/src/cargo/core/workspace.rs b/src/cargo/core/workspace.rs
@@ -26,9 +26,10 @@ use crate::util::context::FeatureUnification;
 use crate::util::edit_distance;
 use crate::util::errors::{CargoResult, ManifestError};
 use crate::util::interning::InternedString;
-use crate::util::lints::{
-    analyze_cargo_lints_table, blanket_hint_mostly_unused, check_im_a_teapot,
-};
+use crate::util::lints::analyze_cargo_lints_table;
+use crate::util::lints::blanket_hint_mostly_unused;
+use crate::util::lints::check_im_a_teapot;
+use crate::util::lints::implicit_minimum_version_req;
 use crate::util::toml::{InheritableFields, read_manifest};
 use crate::util::{
     Filesystem, GlobalContext, IntoUrl, context::CargoResolverConfig, context::ConfigRelativePath,
@@ -1296,6 +1297,7 @@ impl<'gctx> Workspace<'gctx> {
                 self.gctx,
             )?;
             check_im_a_teapot(pkg, &path, &cargo_lints, &mut error_count, self.gctx)?;
+            implicit_minimum_version_req(pkg, &path, &cargo_lints, &mut error_count, self.gctx)?;
         }
 
         if error_count > 0 {
diff --git a/src/cargo/util/lints/implicit_minimum_version_req.rs b/src/cargo/util/lints/implicit_minimum_version_req.rs
@@ -0,0 +1,259 @@
+use std::collections::HashMap;
+use std::path::Path;
+
+use annotate_snippets::AnnotationKind;
+use annotate_snippets::Group;
+use annotate_snippets::Level;
+use annotate_snippets::Patch;
+use annotate_snippets::Snippet;
+use cargo_platform::Platform;
+use cargo_util_schemas::manifest::TomlToolLints;
+use toml::de::DeValue;
+
+use crate::CargoResult;
+use crate::GlobalContext;
+use crate::core::Manifest;
+use crate::core::Package;
+use crate::util::OptVersionReq;
+use crate::util::lints::Lint;
+use crate::util::lints::LintLevel;
+use crate::util::lints::LintLevelReason;
+use crate::util::lints::get_key_value;
+use crate::util::lints::rel_cwd_manifest_path;
+
+pub const LINT: Lint = Lint {
+    name: "implicit_minimum_version_req",
+    desc: "dependency version requirement without an explicit minimum version",
+    groups: &[],
+    default_level: LintLevel::Allow,
+    edition_lint_opts: None,
+    feature_gate: None,
+    docs: Some(
+        r#"
+### What it does
+
+Checks for dependency version requirements
+that do not explicitly specify a full `major.minor.patch` version requirement,
+such as `serde = "1"` or `serde = "1.0"`.
+
+This lint currently only applies to caret requirements
+(the [default requirements](specifying-dependencies.md#default-requirements)).
+
+### Why it is bad
+
+Version requirements without an explicit full version
+can be misleading about the actual minimum supported version.
+For example,
+`serde = "1"` has an implicit minimum bound of `1.0.0`.
+If your code actually requires features from `1.0.219`,
+the implicit minimum bound of `1.0.0` gives a false impression about compatibility.
+
+Specifying the full version helps with:
+
+- Accurate minimum version documentation
+- Better compatibility with `-Z minimal-versions`
+- Clearer dependency constraints for consumers
+
+### Drawbacks
+
+Even with a fully specified version,
+the minimum bound might still be incorrect if untested.
+This lint helps make the minimum version requirement explicit
+but doesn't guarantee correctness.
+
+### Example
+
+```toml
+[dependencies]
+serde = "1"
+```
+
+Should be written as a full specific version:
+
+```toml
+[dependencies]
+serde = "1.0.219"
+```
+"#,
+    ),
+};
+
+pub fn implicit_minimum_version_req(
+    pkg: &Package,
+    manifest_path: &Path,
+    cargo_lints: &TomlToolLints,
+    error_count: &mut usize,
+    gctx: &GlobalContext,
+) -> CargoResult<()> {
+    let manifest = pkg.manifest();
+    let (lint_level, reason) = LINT.level(
+        cargo_lints,
+        manifest.edition(),
+        manifest.unstable_features(),
+    );
+
+    if lint_level == LintLevel::Allow {
+        return Ok(());
+    }
+
+    let document = manifest.document();
+    let contents = manifest.contents();
+    let manifest_path = rel_cwd_manifest_path(manifest_path, gctx);
+    let target_key_for_platform = target_key_for_platform(&manifest);
+
+    for dep in manifest.dependencies().iter() {
+        let version_req = dep.version_req();
+        let Some(suggested_req) = get_suggested_version_req(&version_req) else {
+            continue;
+        };
+
+        let name_in_toml = dep.name_in_toml().as_str();
+        let key_path =
+            if let Some(cfg) = dep.platform().and_then(|p| target_key_for_platform.get(p)) {
+                &["target", &cfg, dep.kind().kind_table(), name_in_toml][..]
+            } else {
+                &[dep.kind().kind_table(), name_in_toml][..]
+            };
+
+        let Some(span) = span_of_version_req(document, key_path) else {
+            continue;
+        };
+
+        let report = report(
+            lint_level,
+            reason,
+            span,
+            contents,
+            &manifest_path,
+            &suggested_req,
+        );
+
+        if lint_level.is_error() {
+            *error_count += 1;
+        }
+        gctx.shell().print_report(&report, lint_level.force())?;
+    }
+
+    Ok(())
+}
+
+pub fn span_of_version_req<'doc>(
+    document: &'doc toml::Spanned<toml::de::DeTable<'static>>,
+    path: &[&str],
+) -> Option<std::ops::Range<usize>> {
+    let (_key, value) = get_key_value(document, path)?;
+
+    match value.as_ref() {
+        DeValue::String(_) => Some(value.span()),
+        DeValue::Table(map) if map.get("workspace").is_some() => {
+            // We only lint non-workspace-inherited dependencies
+            None
+        }
+        DeValue::Table(map) => {
+            let Some(v) = map.get("version") else {
+                panic!("version must be specified or workspace-inherited");
+            };
+            Some(v.span())
+        }
+        _ => unreachable!("dependency must be string or table"),
+    }
+}
+
+fn report<'a>(
+    lint_level: LintLevel,
+    reason: LintLevelReason,
+    span: std::ops::Range<usize>,
+    contents: &'a str,
+    manifest_path: &str,
+    suggested_req: &str,
+) -> [Group<'a>; 2] {
+    let level = lint_level.to_diagnostic_level();
+    let emitted_source = LINT.emitted_source(lint_level, reason);
+    let replacement = format!(r#""{suggested_req}""#);
+    let label = "missing full version components";
+    let secondary_title = "consider specifying full `major.minor.patch` version components";
+    [
+        level.clone().primary_title(LINT.desc).element(
+            Snippet::source(contents)
+                .path(manifest_path.to_owned())
+                .annotation(AnnotationKind::Primary.span(span.clone()).label(label)),
+        ),
+        Level::HELP
+            .secondary_title(secondary_title)
+            .element(Snippet::source(contents).patch(Patch::new(span.clone(), replacement)))
+            .element(Level::NOTE.message(emitted_source)),
+    ]
+}
+
+fn get_suggested_version_req(req: &OptVersionReq) -> Option<String> {
+    use semver::Op;
+    let OptVersionReq::Req(req) = req else {
+        return None;
+    };
+    let mut has_suggestions = false;
+    let mut comparators = Vec::new();
+
+    for mut cmp in req.comparators.iter().cloned() {
+        match cmp.op {
+            Op::Caret | Op::GreaterEq => {
+                // Only focus on comparator that has only `major` or `major.minor`
+                if cmp.minor.is_some() && cmp.patch.is_some() {
+                    comparators.push(cmp);
+                    continue;
+                } else {
+                    has_suggestions = true;
+                    cmp.minor.get_or_insert(0);
+                    cmp.patch.get_or_insert(0);
+                    comparators.push(cmp);
+                }
+            }
+            Op::Exact | Op::Tilde | Op::Wildcard | Op::Greater | Op::Less | Op::LessEq => {
+                comparators.push(cmp);
+                continue;
+            }
+            _ => panic!("unknown comparator in `{cmp}`"),
+        }
+    }
+
+    if !has_suggestions {
+        return None;
+    }
+
+    // This is a lossy suggestion that
+    //
+    // * extra spaces are removed
+    // * caret operator `^` is stripped
+    let mut suggestion = String::new();
+
+    for cmp in &comparators {
+        if !suggestion.is_empty() {
+            suggestion.push_str(", ");
+        }
+        let s = cmp.to_string();
+
+        if cmp.op == Op::Caret {
+            suggestion.push_str(s.strip_prefix('^').unwrap_or(&s));
+        } else {
+            suggestion.push_str(&s);
+        }
+    }
+
+    Some(suggestion)
+}
+
+/// A map from parsed `Platform` to their original TOML key strings.
+/// This is needed for constructing TOML key paths in diagnostics.
+///
+/// This is only relevant for package dependencies.
+fn target_key_for_platform(manifest: &Manifest) -> HashMap<Platform, String> {
+    manifest
+        .normalized_toml()
+        .target
+        .as_ref()
+        .map(|map| {
+            map.keys()
+                .map(|k| (k.parse().expect("already parsed"), k.clone()))
+                .collect()
+        })
+        .unwrap_or_default()
+}
diff --git a/src/cargo/util/lints/mod.rs b/src/cargo/util/lints/mod.rs
@@ -8,8 +8,16 @@ use std::fmt::Display;
 use std::ops::Range;
 use std::path::Path;
 
+mod implicit_minimum_version_req;
+pub use implicit_minimum_version_req::implicit_minimum_version_req;
+
 const LINT_GROUPS: &[LintGroup] = &[TEST_DUMMY_UNSTABLE];
-pub const LINTS: &[Lint] = &[BLANKET_HINT_MOSTLY_UNUSED, IM_A_TEAPOT, UNKNOWN_LINTS];
+pub const LINTS: &[Lint] = &[
+    BLANKET_HINT_MOSTLY_UNUSED,
+    implicit_minimum_version_req::LINT,
+    IM_A_TEAPOT,
+    UNKNOWN_LINTS,
+];
 
 pub fn analyze_cargo_lints_table(
     pkg: &Package,
diff --git a/src/doc/src/reference/lints.md b/src/doc/src/reference/lints.md
@@ -2,6 +2,11 @@
 
 Note: [Cargo's linting system is unstable](unstable.md#lintscargo) and can only be used on nightly toolchains
 
+## Allowed-by-default
+
+These lints are all set to the 'allow' level by default.
+- [`implicit_minimum_version_req`](#implicit_minimum_version_req)
+
 ## Warn-by-default
 
 These lints are all set to the 'warn' level by default.
@@ -36,6 +41,55 @@ hint-mostly-unused = true
 ```
 
 
+## `implicit_minimum_version_req`
+Set to `allow` by default
+
+### What it does
+
+Checks for dependency version requirements
+that do not explicitly specify a full `major.minor.patch` version requirement,
+such as `serde = "1"` or `serde = "1.0"`.
+
+This lint currently only applies to caret requirements
+(the [default requirements](specifying-dependencies.md#default-requirements)).
+
+### Why it is bad
+
+Version requirements without an explicit full version
+can be misleading about the actual minimum supported version.
+For example,
+`serde = "1"` has an implicit minimum bound of `1.0.0`.
+If your code actually requires features from `1.0.219`,
+the implicit minimum bound of `1.0.0` gives a false impression about compatibility.
+
+Specifying the full version helps with:
+
+- Accurate minimum version documentation
+- Better compatibility with `-Z minimal-versions`
+- Clearer dependency constraints for consumers
+
+### Drawbacks
+
+Even with a fully specified version,
+the minimum bound might still be incorrect if untested.
+This lint helps make the minimum version requirement explicit
+but doesn't guarantee correctness.
+
+### Example
+
+```toml
+[dependencies]
+serde = "1"
+```
+
+Should be written as a full specific version:
+
+```toml
+[dependencies]
+serde = "1.0.219"
+```
+
+
 ## `unknown_lints`
 Set to `warn` by default
 
diff --git a/tests/testsuite/lints/implicit_minimum_version_req.rs b/tests/testsuite/lints/implicit_minimum_version_req.rs
