feat(add/install): check if given crate argument would be valid with inserted @ symbol (#15441)

Suggest to user to use a crate name with an inserted @ before the first
invalid package name character

Fixes #15318

<!--
Thanks for submitting a pull request 🎉! Here are some tips for you:

* If this is your first contribution, read "Cargo Contribution Guide"
first:
  https://doc.crates.io/contrib/
* Run `cargo fmt --all` to format your code changes.
* Small commits and pull requests are always preferable and easy to
review.
* If your idea is large and needs feedback from the community, read how:
  https://doc.crates.io/contrib/process/#working-on-large-features
* Cargo takes care of compatibility. Read our design principles:
  https://doc.crates.io/contrib/design.html
* When changing help text of cargo commands, follow the steps to
generate docs:

https://github.com/rust-lang/cargo/tree/master/src/doc#building-the-man-pages
* If your PR is not finished, set it as "draft" PR or add "WIP" in its
title.
* It's ok to use the CI resources to test your PR, but please don't
abuse them.

### What does this PR try to resolve?

Explain the motivation behind this change.
A clear overview along with an in-depth explanation are helpful.

You can use `Fixes #<issue number>` to associate this PR to an existing
issue.

### How should we test and review this PR?

Demonstrate how you test this change and guide reviewers through your
PR.
With a smooth review process, a pull request usually gets reviewed
quicker.

If you don't know how to write and run your tests, please read the
guide:
https://doc.crates.io/contrib/tests

### Additional information

Other information you want to mention in this PR, such as prior arts,
future extensions, an unresolved problem, or a TODO list.
-->

Author: epage

Cargo.lock

@@ -216,6 +216,7 @@ tracing = { workspace = true, features = ["attributes"] }
 tracing-subscriber.workspace = true
 unicase.workspace = true
 unicode-width.workspace = true
+unicode-xid.workspace = true
 url.workspace = true
 walkdir.workspace = true
 

Cargo.toml

@@ -8,6 +8,7 @@ use cargo::ops;
 use cargo::util::IntoUrl;
 use cargo::util::VersionExt;
 use cargo::CargoResult;
+use cargo_util_schemas::manifest::PackageName;
 use itertools::Itertools;
 use semver::VersionReq;
 
@@ -133,6 +134,22 @@ pub fn exec(gctx: &mut GlobalContext, args: &ArgMatches) -> CliResult {
         .collect::<crate::CargoResult<Vec<_>>>()?;
 
     for (crate_name, _) in krates.iter() {
+        let package_name = PackageName::new(crate_name);
+        if !crate_name.contains("@") && package_name.is_err() {
+            for (idx, ch) in crate_name.char_indices() {
+                if !(unicode_xid::UnicodeXID::is_xid_continue(ch) || ch == '-') {
+                    let mut suggested_crate_name = crate_name.to_string();
+                    suggested_crate_name.insert_str(idx, "@");
+                    if let Ok((_, Some(_))) = parse_crate(&suggested_crate_name.as_str()) {
+                        let err = package_name.unwrap_err();
+                        return Err(
+                            anyhow::format_err!("{err}\n\n\
+                                help: if this is meant to be a package name followed by a version, insert an `@` like `{suggested_crate_name}`").into());
+                    }
+                }
+            }
+        }
+
         if let Some(toolchain) = crate_name.strip_prefix("+") {
             return Err(anyhow!(
                 "invalid character `+` in package name: `+{toolchain}`

src/bin/cargo/commands/install.rs

@@ -28,7 +28,23 @@ impl CrateSpec {
             .map(|(n, v)| (n, Some(v)))
             .unwrap_or((pkg_id, None));
 
-        PackageName::new(name)?;
+        let package_name = PackageName::new(name);
+        if !pkg_id.contains("@") && package_name.is_err() {
+            for (idx, ch) in pkg_id.char_indices() {
+                if !(unicode_xid::UnicodeXID::is_xid_continue(ch) || ch == '-') {
+                    let mut suggested_pkg_id = pkg_id.to_string();
+                    suggested_pkg_id.insert_str(idx, "@");
+                    if let Ok(_) = CrateSpec::resolve(&suggested_pkg_id.as_str()) {
+                        let err = package_name.unwrap_err();
+                        return Err(
+                            anyhow::format_err!("{err}\n\n\
+                                help: if this is meant to be a package name followed by a version, insert an `@` like `{suggested_pkg_id}`").into());
+                    }
+                }
+            }
+        }
+
+        package_name?;
 
         if let Some(version) = version {
             semver::VersionReq::parse(version)

src/cargo/ops/cargo_add/crate_spec.rs

@@ -0,0 +1 @@
+../add-basic.in/

tests/testsuite/cargo_add/missing_at_in_crate_spec/in

@@ -0,0 +1,24 @@
+use cargo_test_support::compare::assert_ui;
+use cargo_test_support::current_dir;
+use cargo_test_support::file;
+use cargo_test_support::prelude::*;
+use cargo_test_support::str;
+use cargo_test_support::Project;
+
+#[cargo_test]
+fn case() {
+    let project = Project::from_template(current_dir!().join("in"));
+    let project_root = project.root();
+    let cwd = &project_root;
+
+    snapbox::cmd::Command::cargo_ui()
+        .arg("add")
+        .arg_line("my-package=1.0.0")
+        .current_dir(cwd)
+        .assert()
+        .code(101)
+        .stdout_eq(str![""])
+        .stderr_eq(file!["stderr.term.svg"]);
+
+    assert_ui().subset_matches(current_dir!().join("out"), &project_root);
+}

tests/testsuite/cargo_add/missing_at_in_crate_spec/mod.rs

@@ -0,0 +1,6 @@
+[workspace]
+
+[package]
+name = "cargo-list-test-fixture"
+version = "0.0.0"
+edition = "2015"

tests/testsuite/cargo_add/missing_at_in_crate_spec/out/Cargo.toml

@@ -65,6 +65,7 @@ mod locked_unchanged;
 mod lockfile_updated;
 mod manifest_path_package;
 mod merge_activated_features;
+mod missing_at_in_crate_spec;
 mod multiple_conflicts_with_features;
 mod multiple_conflicts_with_rename;
 mod namever;

tests/testsuite/cargo_add/missing_at_in_crate_spec/stderr.term.svg

@@ -396,6 +396,20 @@ fn bad_version() {
         .run();
 }
 
+#[cargo_test]
+fn missing_at_symbol_before_version() {
+    pkg("foo", "0.0.1");
+    cargo_process("install foo=0.2.0")
+        .with_status(101)
+        .with_stderr_data(str![[r#"
+[ERROR] invalid character `=` in package name: `foo=0.2.0`, characters must be Unicode XID characters (numbers, `-`, `_`, or most letters)
+
+[HELP] if this is meant to be a package name followed by a version, insert an `@` like `foo@=0.2.0`
+
+"#]])
+        .run();
+}
+
 #[cargo_test]
 fn bad_paths() {
     cargo_process("install")