#441: Add '--fuzzy' and '--multiple' options for 'find' command

CHANGELOG.md

@@ -15,6 +15,8 @@
     which includes the serialized registry content in the output.
     This may be useful if you're consuming the `--api` output to back up with another tool,
     but don't have a good way to check the registry keys directly.
+  * CLI: The `find` command now supports `--fuzzy` and `--multiple` options.
+    This is also available for the `api` command's `findTitle` request.
 * Changed:
   * When the game list is filtered,
     the summary line (e.g., "1 of 10 games") now reflects the filtered totals.
@@ -32,6 +34,8 @@
     Previously, Ludusavi would make a backup folder for the game including the space,
     but the OS (namely Windows) would remove the space from the folder title,
     causing unpredictable behavior when Ludusavi couldn't find the expected folder name.
+  * CLI: `find --normalized` now better prioritizes the closest match
+    when multiple manifest entries have the same normalized title.
 
 ## v0.27.0 (2024-11-19)
 

Cargo.toml

@@ -44,6 +44,7 @@ sha1 = "0.10.6"
 shlex = "1.3.0"
 signal-hook = "0.3.17"
 steamlocate = "2.0.0"
+strsim = "0.11.1"
 tokio = { version = "1.40.0", features = ["macros", "time"] }
 typed-path = "0.9.2"
 unic-langid = "0.9.5"

src/cli.rs

@@ -597,13 +597,15 @@ pub fn run(sub: Subcommand, no_manifest_update: bool, try_manifest_update: bool)
         }
         Subcommand::Find {
             api,
+            multiple,
             path,
             backup,
             restore,
             steam_id,
             gog_id,
             lutris_id,
             normalized,
+            fuzzy,
             disabled,
             partial,
             names,
@@ -623,11 +625,13 @@ pub fn run(sub: Subcommand, no_manifest_update: bool, try_manifest_update: bool)
 
             let title_finder = TitleFinder::new(&config, &manifest, layout.restorable_game_set());
             let found = title_finder.find(TitleQuery {
+                multiple,
                 names: names.clone(),
                 steam_id,
                 gog_id,
                 lutris_id,
                 normalized,
+                fuzzy,
                 backup,
                 restore,
                 disabled,

src/cli/api.rs

@@ -1,11 +1,13 @@
 use std::io::Read;
 
+use itertools::Itertools;
+
 use crate::{
     lang::TRANSLATOR,
     path::StrictPath,
     prelude::Error,
     resource::{config::Config, manifest::Manifest},
-    scan::{layout::BackupLayout, TitleFinder, TitleQuery},
+    scan::{compare_ranked_titles, layout::BackupLayout, TitleFinder, TitleQuery},
 };
 
 /// The full input to the `api` command.
@@ -63,14 +65,19 @@ pub mod request {
     ///
     /// Precedence: Steam ID -> GOG ID -> Lutris ID -> exact names -> normalized names.
     /// Once a match is found for one of these options,
-    /// Ludusavi will stop looking and return that match.
+    /// Ludusavi will stop looking and return that match,
+    /// unless you set `multiple: true`, in which case,
+    /// the results will be sorted by how well they match.
     ///
     /// Depending on the options chosen, there may be multiple matches, but the default is a single match.
     ///
     /// Aliases will be resolved to the target title.
     #[derive(Debug, Default, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
     #[serde(default, rename_all = "camelCase")]
     pub struct FindTitle {
+        /// Keep looking for all potential matches,
+        /// instead of stopping at the first match.
+        pub multiple: bool,
         /// Ensure the game is recognized in a backup context.
         pub backup: bool,
         /// Ensure the game is recognized in a restore context.
@@ -85,6 +92,9 @@ pub mod request {
         /// Ignores capitalization, "edition" suffixes, year suffixes, and some special symbols.
         /// This may find multiple games for a single input.
         pub normalized: bool,
+        /// Look up games with fuzzy matching.
+        /// This may find multiple games for a single input.
+        pub fuzzy: bool,
         /// Select games that are disabled.
         pub disabled: bool,
         /// Select games that have some saves disabled.
@@ -101,8 +111,6 @@ pub mod request {
 }
 
 pub mod response {
-    use std::collections::BTreeSet;
-
     #[derive(Debug, Default, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
     #[serde(default, rename_all = "camelCase")]
     pub struct Error {
@@ -114,7 +122,7 @@ pub mod response {
     #[serde(default, rename_all = "camelCase")]
     pub struct FindTitle {
         /// Any matching titles found.
-        pub titles: BTreeSet<String>,
+        pub titles: Vec<String>,
     }
 
     #[derive(Debug, Default, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
@@ -185,28 +193,38 @@ pub fn process(input: Option<String>, config: &Config, manifest: &Manifest) -> R
     for request in input.requests {
         match request {
             Request::FindTitle(request::FindTitle {
+                multiple,
                 backup,
                 restore,
                 steam_id,
                 gog_id,
                 lutris_id,
                 normalized,
+                fuzzy,
                 disabled,
                 partial,
                 names,
             }) => {
                 let titles = title_finder.find(TitleQuery {
+                    multiple,
                     names,
                     steam_id,
                     gog_id,
                     lutris_id,
                     normalized,
+                    fuzzy,
                     backup,
                     restore,
                     disabled,
                     partial,
                 });
 
+                let titles: Vec<_> = titles
+                    .into_iter()
+                    .sorted_by(compare_ranked_titles)
+                    .map(|(name, _info)| name)
+                    .collect();
+
                 responses.push(Response::FindTitle(response::FindTitle { titles }));
             }
             Request::CheckAppUpdate(request::CheckAppUpdate {}) => match crate::metadata::Release::fetch_sync() {
@@ -230,8 +248,6 @@ pub fn process(input: Option<String>, config: &Config, manifest: &Manifest) -> R
 
 #[cfg(test)]
 mod tests {
-    use std::collections::BTreeSet;
-
     use super::*;
     use pretty_assertions::assert_eq;
 
@@ -270,7 +286,7 @@ mod tests {
     pub fn serialize_output() {
         let output = Output::Success {
             responses: vec![Response::FindTitle(response::FindTitle {
-                titles: BTreeSet::from(["foo".to_string()]),
+                titles: vec!["foo".to_string()],
             })],
         };
         let serialized = serde_json::to_string_pretty(&output).unwrap();

src/cli/parse.rs

@@ -301,7 +301,9 @@ pub enum Subcommand {
     ///
     /// Precedence: Steam ID -> GOG ID -> Lutris ID -> exact names -> normalized names.
     /// Once a match is found for one of these options,
-    /// Ludusavi will stop looking and return that match.
+    /// Ludusavi will stop looking and return that match,
+    /// unless you set `--multiple`, in which case,
+    /// the results will be sorted by how well they match.
     ///
     /// If there are no matches, Ludusavi will exit with an error.
     /// Depending on the options chosen, there may be multiple matches, but the default is a single match.
@@ -315,6 +317,11 @@ pub enum Subcommand {
         #[clap(long)]
         api: bool,
 
+        /// Keep looking for all potential matches,
+        /// instead of stopping at the first match.
+        #[clap(long)]
+        multiple: bool,
+
         /// Directory in which to find backups.
         /// When unset, this defaults to the restore path from the config file.
         #[clap(long, value_parser = parse_strict_path)]
@@ -346,6 +353,11 @@ pub enum Subcommand {
         #[clap(long)]
         normalized: bool,
 
+        /// Look up games with fuzzy matching.
+        /// This may find multiple games for a single input.
+        #[clap(long)]
+        fuzzy: bool,
+
         /// Select games that are disabled.
         #[clap(long)]
         disabled: bool,
@@ -1153,13 +1165,15 @@ mod tests {
                 try_manifest_update: false,
                 sub: Some(Subcommand::Find {
                     api: false,
+                    multiple: false,
                     path: None,
                     backup: false,
                     restore: false,
                     steam_id: None,
                     gog_id: None,
                     lutris_id: None,
                     normalized: false,
+                    fuzzy: false,
                     disabled: false,
                     partial: false,
                     names: vec![],
@@ -1175,6 +1189,7 @@ mod tests {
                 "ludusavi",
                 "find",
                 "--api",
+                "--multiple",
                 "--path",
                 "tests/backup",
                 "--backup",
@@ -1186,6 +1201,7 @@ mod tests {
                 "--lutris-id",
                 "slug",
                 "--normalized",
+                "--fuzzy",
                 "--disabled",
                 "--partial",
                 "game1",
@@ -1197,13 +1213,15 @@ mod tests {
                 try_manifest_update: false,
                 sub: Some(Subcommand::Find {
                     api: true,
+                    multiple: true,
                     path: Some(StrictPath::relative(s("tests/backup"), Some(repo_raw()))),
                     backup: true,
                     restore: true,
                     steam_id: Some(101),
                     gog_id: Some(102),
                     lutris_id: Some("slug".to_string()),
                     normalized: true,
+                    fuzzy: true,
                     disabled: true,
                     partial: true,
                     names: vec![s("game1"), s("game2")],

src/cli/report.rs

@@ -8,8 +8,8 @@ use crate::{
     prelude::StrictPath,
     resource::manifest::Os,
     scan::{
-        layout::Backup, registry, BackupError, BackupInfo, DuplicateDetector, OperationStatus, OperationStepDecision,
-        ScanChange, ScanInfo,
+        compare_ranked_titles_ref, layout::Backup, registry, BackupError, BackupInfo, DuplicateDetector,
+        OperationStatus, OperationStepDecision, ScanChange, ScanInfo, TitleMatch,
     },
 };
 
@@ -177,7 +177,11 @@ enum ApiGame {
         backups: Vec<ApiBackup>,
     },
     /// Used by the `find` command.
-    Found {},
+    Found {
+        /// How well the title matches the query.
+        /// Range: 0.0 to 1.0 (higher is better).
+        score: Option<f64>,
+    },
 }
 
 #[derive(Debug, serde::Serialize, schemars::JsonSchema)]
@@ -599,16 +603,20 @@ impl Reporter {
         }
     }
 
-    pub fn add_found_titles(&mut self, names: &BTreeSet<String>) {
+    pub fn add_found_titles(&mut self, games: &BTreeMap<String, TitleMatch>) {
         match self {
             Self::Standard { parts, .. } => {
-                for name in names {
+                let games: Vec<_> = games.iter().sorted_by(compare_ranked_titles_ref).collect();
+
+                for (name, _info) in games {
                     parts.push(name.to_owned());
                 }
             }
             Self::Json { output } => {
-                for name in names {
-                    output.games.insert(name.to_owned(), ApiGame::Found {});
+                for (name, info) in games {
+                    output
+                        .games
+                        .insert(name.to_owned(), ApiGame::Found { score: info.score });
                 }
             }
         }

src/scan.rs

@@ -26,7 +26,7 @@ pub use self::{
     preview::ScanInfo,
     saves::{ScannedFile, ScannedRegistry, ScannedRegistryValue, ScannedRegistryValues},
     steam::{SteamShortcut, SteamShortcuts},
-    title::{TitleFinder, TitleQuery},
+    title::{compare_ranked_titles, compare_ranked_titles_ref, TitleFinder, TitleMatch, TitleQuery},
 };
 
 use crate::{