Make future-incompat-report output more user-friendly

When the user enables `--future-incompat-report`, we now display
a high-level summary of the problem, as well as several suggestions
for fixing the affected crates.

The command `cargo report future-incompatibilities` now takes
a `--crate` option, which can be used to display a report
(including the actual lint messages) for a single crate.
When this option is not used, we display the report for all
crates.

Author: Aaron1011

src/bin/cargo/commands/report.rs

@@ -18,6 +18,10 @@ pub fn cli() -> App {
                         "identifier of the report generated by a Cargo command invocation",
                     )
                     .value_name("id"),
+                )
+                .arg(
+                    opt("crate", "identifier of the crate to display a report for")
+                        .value_name("crate"),
                 ),
         )
 }
@@ -38,7 +42,8 @@ fn report_future_incompatibilies(config: &Config, args: &ArgMatches<'_>) -> CliR
     let id = args
         .value_of_u32("id")?
         .unwrap_or_else(|| reports.last_id());
-    let report = reports.get_report(id, config)?;
+    let krate = args.value_of("crate");
+    let report = reports.get_report(id, config, krate)?;
     drop_println!(config, "{}", REPORT_PREAMBLE);
     drop(config.shell().print_ansi_stdout(report.as_bytes()));
     Ok(())

src/cargo/core/compiler/future_incompat.rs

@@ -1,12 +1,10 @@
 //! Support for future-incompatible warning reporting.
 
-use crate::core::{Dependency, PackageId, Workspace};
-use crate::sources::SourceConfigMap;
+use crate::core::{PackageId, Workspace};
 use crate::util::{iter_join, CargoResult, Config};
 use anyhow::{bail, format_err, Context};
 use serde::{Deserialize, Serialize};
-use std::collections::{BTreeSet, HashMap, HashSet};
-use std::fmt::Write as _;
+use std::collections::BTreeMap;
 use std::io::{Read, Write};
 
 pub const REPORT_PREAMBLE: &str = "\
@@ -78,7 +76,10 @@ struct OnDiskReport {
     /// Unique reference to the report for the `--id` CLI flag.
     id: u32,
     /// Report, suitable for printing to the console.
-    report: String,
+    /// Maps crate names to the corresponding report
+    /// We use a `BTreeMap` so that the iteration order
+    /// is stable across multiple runs of `cargo`
+    per_crate: BTreeMap<String, String>,
 }
 
 impl Default for OnDiskReports {
@@ -109,7 +110,7 @@ impl OnDiskReports {
         };
         let report = OnDiskReport {
             id: current_reports.next_id,
-            report: render_report(ws, per_package_reports),
+            per_crate: render_report(per_package_reports),
         };
         current_reports.next_id += 1;
         current_reports.reports.push(report);
@@ -176,7 +177,12 @@ impl OnDiskReports {
         self.reports.last().map(|r| r.id).unwrap()
     }
 
-    pub fn get_report(&self, id: u32, config: &Config) -> CargoResult<String> {
+    pub fn get_report(
+        &self,
+        id: u32,
+        config: &Config,
+        package: Option<&str>,
+    ) -> CargoResult<String> {
         let report = self.reports.iter().find(|r| r.id == id).ok_or_else(|| {
             let available = iter_join(self.reports.iter().map(|r| r.id.to_string()), ", ");
             format_err!(
@@ -186,25 +192,45 @@ impl OnDiskReports {
                 available
             )
         })?;
-        let report = if config.shell().err_supports_color() {
-            report.report.clone()
+        let to_display = if let Some(package) = package {
+            report
+                .per_crate
+                .get(package)
+                .ok_or_else(|| {
+                    format_err!(
+                        "could not find package with ID `{}`\n
+                Available packages are: {}\n
+                Omit the `--crate` flag to display a report for all crates",
+                        package,
+                        iter_join(report.per_crate.keys(), ", ")
+                    )
+                })?
+                .clone()
         } else {
-            strip_ansi_escapes::strip(&report.report)
+            report
+                .per_crate
+                .values()
+                .cloned()
+                .collect::<Vec<_>>()
+                .join("\n")
+        };
+        let to_display = if config.shell().err_supports_color() {
+            to_display
+        } else {
+            strip_ansi_escapes::strip(&to_display)
                 .map(|v| String::from_utf8(v).expect("utf8"))
                 .expect("strip should never fail")
         };
-        Ok(report)
+        Ok(to_display)
     }
 }
 
-fn render_report(
-    ws: &Workspace<'_>,
-    per_package_reports: &[FutureIncompatReportPackage],
-) -> String {
-    let mut per_package_reports: Vec<_> = per_package_reports.iter().collect();
-    per_package_reports.sort_by_key(|r| r.package_id);
-    let mut rendered = String::new();
-    for per_package in &per_package_reports {
+fn render_report(per_package_reports: &[FutureIncompatReportPackage]) -> BTreeMap<String, String> {
+    let mut report: BTreeMap<String, String> = BTreeMap::new();
+    for per_package in per_package_reports {
+        let rendered = report
+            .entry(per_package.package_id.to_string())
+            .or_default();
         rendered.push_str(&format!(
             "The package `{}` currently triggers the following future \
              incompatibility lints:\n",
@@ -218,72 +244,6 @@ fn render_report(
                     .map(|l| format!("> {}\n", l)),
             );
         }
-        rendered.push('\n');
-    }
-    if let Some(s) = render_suggestions(ws, &per_package_reports) {
-        rendered.push_str(&s);
-    }
-    rendered
-}
-
-fn render_suggestions(
-    ws: &Workspace<'_>,
-    per_package_reports: &[&FutureIncompatReportPackage],
-) -> Option<String> {
-    // This in general ignores all errors since this is opportunistic.
-    let _lock = ws.config().acquire_package_cache_lock().ok()?;
-    // Create a set of updated registry sources.
-    let map = SourceConfigMap::new(ws.config()).ok()?;
-    let package_ids: BTreeSet<_> = per_package_reports
-        .iter()
-        .map(|r| r.package_id)
-        .filter(|pkg_id| pkg_id.source_id().is_registry())
-        .collect();
-    let source_ids: HashSet<_> = package_ids
-        .iter()
-        .map(|pkg_id| pkg_id.source_id())
-        .collect();
-    let mut sources: HashMap<_, _> = source_ids
-        .into_iter()
-        .filter_map(|sid| {
-            let source = map.load(sid, &HashSet::new()).ok()?;
-            Some((sid, source))
-        })
-        .collect();
-    // Query the sources for new versions.
-    let mut suggestions = String::new();
-    for pkg_id in package_ids {
-        let source = match sources.get_mut(&pkg_id.source_id()) {
-            Some(s) => s,
-            None => continue,
-        };
-        let dep = Dependency::parse(pkg_id.name(), None, pkg_id.source_id()).ok()?;
-        let summaries = source.query_vec(&dep).ok()?;
-        let versions = itertools::sorted(
-            summaries
-                .iter()
-                .map(|summary| summary.version())
-                .filter(|version| *version > pkg_id.version()),
-        );
-        let versions = versions.map(|version| version.to_string());
-        let versions = iter_join(versions, ", ");
-        if !versions.is_empty() {
-            writeln!(
-                suggestions,
-                "{} has the following newer versions available: {}",
-                pkg_id, versions
-            )
-            .unwrap();
-        }
-    }
-    if suggestions.is_empty() {
-        None
-    } else {
-        Some(format!(
-            "The following packages appear to have newer versions available.\n\
-             You may want to consider updating them to a newer version to see if the \
-             issue has been fixed.\n\n{}",
-            suggestions
-        ))
     }
+    report
 }

src/cargo/core/compiler/job_queue.rs

@@ -75,11 +75,13 @@ use crate::core::compiler::future_incompat::{
     FutureBreakageItem, FutureIncompatReportPackage, OnDiskReports,
 };
 use crate::core::resolver::ResolveBehavior;
+use crate::core::{Dependency, Workspace};
 use crate::core::{PackageId, Shell, TargetKind};
+use crate::sources::SourceConfigMap;
 use crate::util::diagnostic_server::{self, DiagnosticPrinter};
 use crate::util::machine_message::{self, Message as _};
 use crate::util::CargoResult;
-use crate::util::{self, internal, profile};
+use crate::util::{self, internal, iter_join, profile};
 use crate::util::{Config, DependencyQueue, Progress, ProgressStyle, Queue};
 
 /// This structure is backed by the `DependencyQueue` type and manages the
@@ -911,15 +913,12 @@ impl<'cfg> DrainState<'cfg> {
         }
 
         // Get a list of unique and sorted package name/versions.
-        let package_vers: BTreeSet<_> = self
+        let package_ids: BTreeSet<_> = self
             .per_package_future_incompat_reports
             .iter()
             .map(|r| r.package_id)
             .collect();
-        let package_vers: Vec<_> = package_vers
-            .into_iter()
-            .map(|pid| pid.to_string())
-            .collect();
+        let package_vers: Vec<_> = package_ids.iter().map(|pid| pid.to_string()).collect();
 
         if should_display_message || bcx.build_config.future_incompat_report {
             drop(bcx.config.shell().warn(&format!(
@@ -934,8 +933,76 @@ impl<'cfg> DrainState<'cfg> {
         let report_id = on_disk_reports.last_id();
 
         if bcx.build_config.future_incompat_report {
-            let rendered = on_disk_reports.get_report(report_id, bcx.config).unwrap();
-            drop(bcx.config.shell().print_ansi_stderr(rendered.as_bytes()));
+            let upstream_info = package_ids
+                .iter()
+                .map(|package_id| {
+                    let manifest = bcx.packages.get_one(*package_id).unwrap().manifest();
+                    format!(
+                        "
+  - {name}
+    - Repository: {url}
+    - Detailed warning command: `cargo report future-incompatibilities --id {id} --crate '{name}'",
+                        name = package_id,
+                        url = manifest
+                            .metadata()
+                            .repository
+                            .as_deref()
+                            .unwrap_or("<not found>"),
+                        id = report_id,
+                    )
+                })
+                .collect::<Vec<_>>()
+                .join("\n");
+
+            let (compat, incompat) =
+                get_updates(bcx.ws, &package_ids).unwrap_or((String::new(), String::new()));
+
+            let compat_message = if !compat.is_empty() {
+                format!(
+                    "
+- Some affected dependencies have minor or patch version updates available:
+{compat}",
+                    compat = compat
+                )
+            } else {
+                String::new()
+            };
+
+            let incompat_message = if !incompat.is_empty() {
+                format!(
+                    "
+- If a minor dependency update does not help, you can try updating to a new 
+  major version of those dependencies. You have to do this manually:
+{incompat}
+                ",
+                    incompat = incompat
+                )
+            } else {
+                String::new()
+            };
+
+            drop(bcx.config.shell().note(&format!(
+                "
+To solve this problem, you can try the following approaches:
+
+{compat_message}
+{incompat_message}
+- If the issue is not solved by updating the dependencies, a fix has to be
+  implemented by those dependencies. You can help with that by notifying the
+  maintainers of this problem (e.g. by creating a bug report) or by proposing a
+  fix to the maintainers (e.g. by creating a pull request):
+  {upstream_info}
+
+- If waiting for an upstream fix is not an option, you can use the `[patch]`
+  section in `Cargo.toml` to use your own version of the dependency. For more
+  information, see:
+  https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html#the-patch-section
+            ",
+                upstream_info = upstream_info,
+                compat_message = compat_message,
+                incompat_message = incompat_message
+            )));
+
             drop(bcx.config.shell().note(&format!(
                 "this report can be shown with `cargo report \
                  future-incompatibilities -Z future-incompat-report --id {}`",
@@ -1283,3 +1350,75 @@ feature resolver. Try updating to diesel 1.4.8 to fix this error.
         Ok(())
     }
 }
+
+// Returns a pair (compatible_updates, incompatible_updates),
+// of semver-compatible and semver-incompatible update versions,
+// respectively.
+fn get_updates(ws: &Workspace<'_>, package_ids: &BTreeSet<PackageId>) -> Option<(String, String)> {
+    // This in general ignores all errors since this is opportunistic.
+    let _lock = ws.config().acquire_package_cache_lock().ok()?;
+    // Create a set of updated registry sources.
+    let map = SourceConfigMap::new(ws.config()).ok()?;
+    let package_ids: BTreeSet<_> = package_ids
+        .iter()
+        .filter(|pkg_id| pkg_id.source_id().is_registry())
+        .collect();
+    let source_ids: HashSet<_> = package_ids
+        .iter()
+        .map(|pkg_id| pkg_id.source_id())
+        .collect();
+    let mut sources: HashMap<_, _> = source_ids
+        .into_iter()
+        .filter_map(|sid| {
+            let source = map.load(sid, &HashSet::new()).ok()?;
+            Some((sid, source))
+        })
+        .collect();
+    // Query the sources for new versions.
+    let mut compatible = String::new();
+    let mut incompatible = String::new();
+    for pkg_id in package_ids {
+        let source = match sources.get_mut(&pkg_id.source_id()) {
+            Some(s) => s,
+            None => continue,
+        };
+        let dep = Dependency::parse(pkg_id.name(), None, pkg_id.source_id()).ok()?;
+        let summaries = source.query_vec(&dep).ok()?;
+        let (mut compatible_versions, mut incompatible_versions): (Vec<_>, Vec<_>) = summaries
+            .iter()
+            .map(|summary| summary.version())
+            .filter(|version| *version > pkg_id.version())
+            .partition(|version| version.major == pkg_id.version().major);
+        compatible_versions.sort();
+        incompatible_versions.sort();
+
+        let compatible_versions = compatible_versions
+            .into_iter()
+            .map(|version| version.to_string());
+        let compatible_versions = iter_join(compatible_versions, ", ");
+
+        let incompatible_versions = incompatible_versions
+            .into_iter()
+            .map(|version| version.to_string());
+        let incompatible_versions = iter_join(incompatible_versions, ", ");
+
+        if !compatible_versions.is_empty() {
+            writeln!(
+                compatible,
+                "{} has the following newer versions available: {}",
+                pkg_id, compatible_versions
+            )
+            .unwrap();
+        }
+
+        if !incompatible_versions.is_empty() {
+            writeln!(
+                incompatible,
+                "{} has the following newer versions available: {}",
+                pkg_id, incompatible_versions
+            )
+            .unwrap();
+        }
+    }
+    Some((compatible, incompatible))
+}