Skip to main content

docsrs_cli/error/
suggestion.rs

1//! The `--suggest` alternative, as data rather than as a sentence.
2//!
3//! Split out of [`super::detail`] because the type has a life of its own: it is
4//! produced by the ranker in [`crate::suggest`], carried by
5//! [`super::ErrorDetail::WithSuggestions`], published by
6//! [`crate::render::error_envelope`] and printed by both renderers. Four callers
7//! across three layers is not a detail of the error catalogue.
8
9/// One ranked `--suggest` alternative.
10///
11/// The ranker used to hand back `Vec<String>` already formatted as
12/// `"option::Option::unwrap (method)"`, and the only place those strings ever
13/// landed was inside `error.message`. An agent that wanted the alternatives had
14/// to split on `"; suggestions: "`, split again on `", "` and then regex the
15/// trailing `"(kind)"` off each entry — parsing prose the CLI had just built out
16/// of data it already held. Keeping the pair typed lets
17/// [`crate::render::error_envelope`] publish `error.suggestions` while the two
18/// renderers keep composing the same sentence for humans, from one source.
19#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
20pub struct Suggestion {
21    /// Item path to retype, without the crate prefix (`option::Option::unwrap`).
22    pub path: String,
23    /// CLI kind the caller would pass alongside `path` (`method`, `variant`, …).
24    ///
25    /// This is the kind the *caller* would retype, not the rustdoc anchor family:
26    /// labelling an associated type `(method)` would send them straight back into
27    /// the same not-found.
28    pub kind: String,
29}
30
31impl Suggestion {
32    /// Build one suggestion from its two parts.
33    pub fn new(path: impl Into<String>, kind: impl Into<String>) -> Self {
34        Self {
35            path: path.into(),
36            kind: kind.into(),
37        }
38    }
39}
40
41/// Render a suggestion list the way both languages print it.
42///
43/// Shared so the English and pt-BR renderers cannot drift into two orderings or
44/// two separators; only the lead-in word differs between them.
45pub(super) fn join_suggestions(items: &[Suggestion]) -> String {
46    if items.is_empty() {
47        return "(none)".to_string();
48    }
49    items
50        .iter()
51        .map(|s| format!("{} ({})", s.path, s.kind))
52        .collect::<Vec<_>>()
53        .join(", ")
54}
55
56#[cfg(test)]
57mod tests {
58    use super::*;
59
60    #[test]
61    fn an_empty_list_reads_as_none_in_the_sentence() {
62        // `--suggest` that ranked nothing still says so out loud; the wire field
63        // is omitted instead, and that asymmetry is deliberate.
64        assert_eq!(join_suggestions(&[]), "(none)");
65    }
66
67    #[test]
68    fn entries_keep_rank_order_and_the_kind_label() {
69        let out = join_suggestions(&[
70            Suggestion::new("option::Option::unwrap", "method"),
71            Suggestion::new("option::Option::unzip", "method"),
72        ]);
73        assert_eq!(
74            out,
75            "option::Option::unwrap (method), option::Option::unzip (method)"
76        );
77    }
78}