tauri-build 2.7.3

// Copyright 2019-2024 Tauri Programme within The Commons Conservancy
// SPDX-License-Identifier: Apache-2.0
// SPDX-License-Identifier: MIT

use std::{
  collections::{BTreeMap, HashMap},
  env, fs,
  path::{Path, PathBuf},
};

use anyhow::{Context, Result};
use tauri_utils::{
  acl::{
    ACL_MANIFESTS_FILE_NAME, APP_ACL_KEY, CAPABILITIES_FILE_NAME,
    capability::Capability,
    get_capabilities,
    manifest::{Manifest, PermissionFile},
    schema::CAPABILITIES_SCHEMA_FOLDER_PATH,
  },
  config::Config,
  platform::Target,
  write_if_changed,
};

use crate::Attributes;

/// Definition of a plugin that is part of the Tauri application instead of having its own crate.
///
/// By default it generates a plugin manifest that parses permissions from the `permissions/$plugin-name` directory.
/// To change the glob pattern that is used to find permissions, use [`Self::permissions_path_pattern`].
///
/// To autogenerate permissions for each of the plugin commands, see [`Self::commands`].
#[derive(Debug, Default, Clone)]
pub struct InlinedPlugin {
  commands: &'static [&'static str],
  permissions_path_pattern: Option<&'static str>,
  default: Option<DefaultPermissionRule>,
}

/// Variants of a generated default permission that can be used on an [`InlinedPlugin`].
#[derive(Debug, Clone)]
pub enum DefaultPermissionRule {
  /// Allow all commands from [`InlinedPlugin::commands`].
  AllowAllCommands,
  /// Allow the given list of permissions.
  ///
  /// Note that the list refers to permissions instead of command names,
  /// so for example a command called `execute` would need to be allowed as `allow-execute`.
  Allow(Vec<String>),
}

impl InlinedPlugin {
  /// Creates a new inlined plugin definition with the default options.
  pub fn new() -> Self {
    Self::default()
  }

  /// Define a list of commands that gets permissions autogenerated in the format of `allow-$command` and `deny-$command`
  /// where $command is the command name in snake_case.
  pub fn commands(mut self, commands: &'static [&'static str]) -> Self {
    self.commands = commands;
    self
  }

  /// Sets a glob pattern that is used to find the permissions of this inlined plugin.
  ///
  /// **Note:** You must emit [rerun-if-changed] instructions for the plugin permissions directory.
  ///
  /// By default it is `./permissions/$plugin-name/**/*`
  pub fn permissions_path_pattern(mut self, pattern: &'static str) -> Self {
    self.permissions_path_pattern.replace(pattern);
    self
  }

  /// Creates a default permission for the plugin using the given rule.
  ///
  /// Alternatively you can pull a permission in the filesystem in the permissions directory, see [`Self::permissions_path_pattern`].
  pub fn default_permission(mut self, default: DefaultPermissionRule) -> Self {
    self.default.replace(default);
    self
  }
}

/// Tauri application permission manifest.
///
/// By default it generates a manifest that parses permissions from the `permissions` directory.
/// To change the glob pattern that is used to find permissions, use [`Self::permissions_path_pattern`].
///
/// To autogenerate permissions for each of the app commands, see [`Self::commands`].
#[derive(Debug, Default, Clone, Copy)]
pub struct AppManifest {
  commands: &'static [&'static str],
  permissions_path_pattern: Option<&'static str>,
}

impl AppManifest {
  /// Creates a new application manifest with the default options.
  pub fn new() -> Self {
    Self::default()
  }

  /// Define a list of commands that gets permissions autogenerated in the format of `allow-$command` and `deny-$command`
  /// where $command is the command name in snake_case.
  pub fn commands(mut self, commands: &'static [&'static str]) -> Self {
    self.commands = commands;
    self
  }

  /// Sets a glob pattern that is used to find the permissions of the app.
  ///
  /// **Note:** You must emit [rerun-if-changed] instructions for the permissions directory.
  ///
  /// By default it is `./permissions/**/*` ignoring any [`InlinedPlugin`].
  pub fn permissions_path_pattern(mut self, pattern: &'static str) -> Self {
    self.permissions_path_pattern.replace(pattern);
    self
  }
}

/// Saves capabilities in a file inside the project, mainly to be read by tauri-cli.
fn save_capabilities(capabilities: &BTreeMap<String, Capability>) -> Result<PathBuf> {
  let dir = Path::new(CAPABILITIES_SCHEMA_FOLDER_PATH);
  fs::create_dir_all(dir)?;

  let path = dir.join(CAPABILITIES_FILE_NAME);
  let json = serde_json::to_string(&capabilities)?;
  write_if_changed(&path, json)?;

  Ok(path)
}

/// Saves ACL manifests in a file inside the project, mainly to be read by tauri-cli.
fn save_acl_manifests(acl_manifests: &BTreeMap<String, Manifest>) -> Result<PathBuf> {
  let dir = Path::new(CAPABILITIES_SCHEMA_FOLDER_PATH);
  fs::create_dir_all(dir)?;

  let path = dir.join(ACL_MANIFESTS_FILE_NAME);
  let json = serde_json::to_string(&acl_manifests)?;
  write_if_changed(&path, json)?;

  Ok(path)
}

/// Read plugin permissions and scope schema from env vars
fn read_plugins_manifests() -> Result<BTreeMap<String, Manifest>> {
  use tauri_utils::acl;

  let permission_map =
    acl::build::read_permissions().context("failed to read plugin permissions")?;
  let mut global_scope_map =
    acl::build::read_global_scope_schemas().context("failed to read global scope schemas")?;

  let mut manifests = BTreeMap::new();

  for (plugin_name, permission_files) in permission_map {
    let global_scope_schema = global_scope_map.remove(&plugin_name);
    let manifest = Manifest::new(permission_files, global_scope_schema);
    manifests.insert(plugin_name, manifest);
  }

  Ok(manifests)
}

struct InlinedPluginsAcl {
  manifests: BTreeMap<String, Manifest>,
  permission_files: BTreeMap<String, Vec<PermissionFile>>,
}

fn inline_plugins(
  out_dir: &Path,
  inlined_plugins: HashMap<&'static str, InlinedPlugin>,
) -> Result<InlinedPluginsAcl> {
  let mut acl_manifests = BTreeMap::new();
  let mut permission_files_map = BTreeMap::new();

  for (name, plugin) in inlined_plugins {
    let plugin_out_dir = out_dir.join("plugins").join(name);
    fs::create_dir_all(&plugin_out_dir)?;

    let mut permission_files = if plugin.commands.is_empty() {
      Vec::new()
    } else {
      let autogenerated = tauri_utils::acl::build::autogenerate_command_permissions(
        &plugin_out_dir,
        plugin.commands,
        "",
        false,
      );

      let default_permissions = plugin.default.map(|default| match default {
        DefaultPermissionRule::AllowAllCommands => autogenerated.allowed,
        DefaultPermissionRule::Allow(permissions) => permissions,
      });
      if let Some(default_permissions) = default_permissions {
        let default_permissions = default_permissions
          .iter()
          .map(|p| format!("\"{p}\""))
          .collect::<Vec<String>>()
          .join(",");
        let default_permission = format!(
          r###"# Automatically generated - DO NOT EDIT!
[default]
permissions = [{default_permissions}]
"###
        );

        let default_permission_path = plugin_out_dir.join("default.toml");

        write_if_changed(&default_permission_path, default_permission)
          .unwrap_or_else(|_| panic!("unable to autogenerate {default_permission_path:?}"));
      }

      tauri_utils::acl::build::define_permissions(
        &PathBuf::from(glob::Pattern::escape(&plugin_out_dir.to_string_lossy()))
          .join("*")
          .to_string_lossy(),
        name,
        &plugin_out_dir,
        |_| true,
      )?
    };

    if let Some(pattern) = plugin.permissions_path_pattern {
      permission_files.extend(tauri_utils::acl::build::define_permissions(
        pattern,
        name,
        &plugin_out_dir,
        |_| true,
      )?);
    } else {
      let default_permissions_path = Path::new("permissions").join(name);
      if default_permissions_path.exists() {
        println!(
          "cargo:rerun-if-changed={}",
          default_permissions_path.display()
        );
      }
      permission_files.extend(tauri_utils::acl::build::define_permissions(
        &PathBuf::from(glob::Pattern::escape(
          &default_permissions_path.to_string_lossy(),
        ))
        .join("**")
        .join("*")
        .to_string_lossy(),
        name,
        &plugin_out_dir,
        |_| true,
      )?);
    }

    permission_files_map.insert(name.into(), permission_files.clone());

    let manifest = tauri_utils::acl::manifest::Manifest::new(permission_files, None);
    acl_manifests.insert(name.into(), manifest);
  }

  Ok(InlinedPluginsAcl {
    manifests: acl_manifests,
    permission_files: permission_files_map,
  })
}

#[derive(Debug)]
struct AppManifestAcl {
  manifest: Manifest,
  permission_files: Vec<PermissionFile>,
}

fn app_manifest_permissions(
  out_dir: &Path,
  manifest: AppManifest,
  inlined_plugins: &HashMap<&'static str, InlinedPlugin>,
) -> Result<AppManifestAcl> {
  let app_out_dir = out_dir.join("app-manifest");
  fs::create_dir_all(&app_out_dir)?;
  let pkg_name = "__app__";

  let mut permission_files = if manifest.commands.is_empty() {
    Vec::new()
  } else {
    let autogenerated_path = Path::new("./permissions/autogenerated");
    tauri_utils::acl::build::autogenerate_command_permissions(
      autogenerated_path,
      manifest.commands,
      "",
      false,
    );
    tauri_utils::acl::build::define_permissions(
      &autogenerated_path.join("*").to_string_lossy(),
      pkg_name,
      &app_out_dir,
      |_| true,
    )?
  };

  if let Some(pattern) = manifest.permissions_path_pattern {
    permission_files.extend(tauri_utils::acl::build::define_permissions(
      pattern,
      pkg_name,
      &app_out_dir,
      |_| true,
    )?);
  } else {
    let default_permissions_path = Path::new("permissions");
    if default_permissions_path.exists() {
      println!(
        "cargo:rerun-if-changed={}",
        default_permissions_path.display()
      );
    }

    let permissions_root = env::current_dir()?.join("permissions");
    let inlined_plugins_permissions: Vec<_> = inlined_plugins
      .keys()
      .map(|name| permissions_root.join(name))
      .flat_map(|p| p.canonicalize())
      .collect();

    permission_files.extend(tauri_utils::acl::build::define_permissions(
      &default_permissions_path
        .join("**")
        .join("*")
        .to_string_lossy(),
      pkg_name,
      &app_out_dir,
      // filter out directories containing inlined plugins
      |p| {
        !inlined_plugins_permissions
          .iter()
          .any(|inlined_path| p.starts_with(inlined_path))
      },
    )?);
  }

  Ok(AppManifestAcl {
    permission_files: permission_files.clone(),
    manifest: tauri_utils::acl::manifest::Manifest::new(permission_files, None),
  })
}

fn validate_capabilities(
  acl_manifests: &BTreeMap<String, Manifest>,
  capabilities: &BTreeMap<String, Capability>,
) -> Result<()> {
  let target = tauri_utils::platform::Target::from_triple(&std::env::var("TARGET").unwrap());

  for capability in capabilities.values() {
    if !capability
      .platforms
      .as_ref()
      .map(|platforms| platforms.contains(&target))
      .unwrap_or(true)
    {
      continue;
    }

    for permission_entry in &capability.permissions {
      let permission_id = permission_entry.identifier();

      let key = permission_id.get_prefix().unwrap_or(APP_ACL_KEY);
      let permission_name = permission_id.get_base();

      let permission_exists = acl_manifests
        .get(key)
        .map(|manifest| {
          // the default permission is always treated as valid, the CLI automatically adds it on the `tauri add` command
          permission_name == "default"
            || manifest.permissions.contains_key(permission_name)
            || manifest.permission_sets.contains_key(permission_name)
        })
        .unwrap_or(false);

      if !permission_exists {
        let mut available_permissions = Vec::new();
        for (key, manifest) in acl_manifests {
          let prefix = if key == APP_ACL_KEY {
            "".to_string()
          } else {
            format!("{key}:")
          };
          if manifest.default_permission.is_some() {
            available_permissions.push(format!("{prefix}default"));
          }
          for p in manifest.permissions.keys() {
            available_permissions.push(format!("{prefix}{p}"));
          }
          for p in manifest.permission_sets.keys() {
            available_permissions.push(format!("{prefix}{p}"));
          }
        }

        let hint = suggest_identifier(permission_id.get(), &available_permissions)
          .map(|suggestion| format!(" (did you mean \"{suggestion}\"?)"))
          .unwrap_or_default();

        anyhow::bail!(
          "Permission {} not found{hint}, expected one of {}",
          permission_id.get(),
          available_permissions.join(", ")
        );
      }
    }
  }

  Ok(())
}

pub fn build(
  out_dir: &Path,
  target: Target,
  config: &Config,
  attributes: &Attributes,
) -> super::Result<()> {
  let mut acl_manifests = read_plugins_manifests()?;

  let app_acl = app_manifest_permissions(
    out_dir,
    attributes.app_manifest,
    &attributes.inlined_plugins,
  )?;
  let has_app_manifest = app_acl.manifest.default_permission.is_some()
    || !app_acl.manifest.permission_sets.is_empty()
    || !app_acl.manifest.permissions.is_empty();
  if has_app_manifest {
    acl_manifests.insert(APP_ACL_KEY.into(), app_acl.manifest);
  }

  let inline_plugins_acl = inline_plugins(out_dir, attributes.inlined_plugins.clone())?;

  acl_manifests.extend(inline_plugins_acl.manifests);

  let acl_manifests_path = save_acl_manifests(&acl_manifests)?;
  fs::copy(acl_manifests_path, out_dir.join(ACL_MANIFESTS_FILE_NAME))?;

  tauri_utils::acl::schema::generate_capability_schema(&acl_manifests, target)?;

  let capabilities_from_files = if let Some(pattern) = attributes.capabilities_path_pattern {
    tauri_utils::acl::build::parse_capabilities(pattern)?
  } else {
    // Emit an absolute watch path: cargo resolves a relative
    // `rerun-if-changed` against the package that owns the build script, while
    // the glob below is resolved against the process working directory.
    // Callers that `set_current_dir` before `try_build[_context]` (for example
    // a crate generating a context byte-identical to the app's) would
    // otherwise watch a `<caller-manifest-dir>/capabilities` that usually does
    // not exist — and a missing watched path is dirty on every fingerprint
    // check, re-running the build script and recompiling the whole downstream
    // chain on every build.
    let capabilities_dir = std::env::current_dir()
      .context("resolve current dir for capabilities watch path")?
      .join("capabilities");
    println!("cargo:rerun-if-changed={}", capabilities_dir.display());
    tauri_utils::acl::build::parse_capabilities("./capabilities/**/*")?
  };
  // the capabilities that are actually resolved at compile time are the ones returned by
  // `get_capabilities`: when the configuration file defines `app > security > capabilities`,
  // the capabilities parsed from the filesystem are only used to resolve the entries that
  // reference them by identifier, and the inlined ones are never seen by this build script
  // otherwise. we must validate that same set so a typo in an inlined permission identifier
  // is reported here instead of panicking later on tauri-codegen's ACL resolution
  let capabilities = get_capabilities(config, capabilities_from_files.clone(), None)
    .context("failed to resolve the capabilities from the Tauri configuration file")?;

  validate_capabilities(&acl_manifests, &capabilities)?;

  let capabilities_path = save_capabilities(&capabilities_from_files)?;
  fs::copy(capabilities_path, out_dir.join(CAPABILITIES_FILE_NAME))?;

  let mut permissions_map = inline_plugins_acl.permission_files;
  if has_app_manifest {
    permissions_map.insert(APP_ACL_KEY.to_string(), app_acl.permission_files);
  }

  // note: `generate_allowed_commands` merges the configuration capabilities itself
  // so it must receive the capabilities parsed from the filesystem
  tauri_utils::acl::build::generate_allowed_commands(
    out_dir,
    Some(capabilities_from_files),
    permissions_map,
  )?;

  Ok(())
}

/// Minimum [`strsim::jaro_winkler`] similarity for a candidate to be suggested as a
/// "did you mean" hint.
///
/// Matches the threshold used by the application-category parser in `tauri-bundler`,
/// so the two suggestion surfaces behave consistently.
const SUGGESTION_CONFIDENCE_THRESHOLD: f64 = 0.8;

/// Returns whether two components match exactly or with one edit or adjacent transposition.
fn components_match(input: &str, candidate: &str) -> bool {
  input == candidate
    || (input.chars().count().max(candidate.chars().count()) >= 4
      && strsim::osa_distance(input, candidate) <= 1)
}

/// Splits an identifier into its namespace (everything before the last `:`) and its base.
fn split_identifier(identifier: &str) -> (Option<&str>, &str) {
  match identifier.rsplit_once(':') {
    Some((namespace, base)) => (Some(namespace), base),
    None => (None, identifier),
  }
}

/// Checks the `-` separated components of two identifier bases.
fn base_components_match(input_parts: &[&str], candidate_base: &str) -> bool {
  candidate_base.split('-').count() == input_parts.len()
    && input_parts
      .iter()
      .zip(candidate_base.split('-'))
      .all(|(a, b)| components_match(a, b))
}

/// Checks whether a candidate namespace is acceptable for the rejected identifier's namespace.
///
/// The namespace must match exactly, unless no candidate uses it (an unknown plugin or a typo in
/// its name), in which case each `:` separated component may contain a single typo.
fn namespaces_match(
  input_namespace: Option<&str>,
  candidate_namespace: Option<&str>,
  input_namespace_known: bool,
) -> bool {
  match (input_namespace, candidate_namespace) {
    (input, candidate) if input == candidate => true,
    (Some(input), Some(candidate)) if !input_namespace_known => {
      input.split(':').count() == candidate.split(':').count()
        && input
          .split(':')
          .zip(candidate.split(':'))
          .all(|(a, b)| components_match(a, b))
    }
    _ => false,
  }
}

/// Returns the identifier from `candidates` that most closely resembles `input`, if any
/// is similar enough to be worth suggesting.
///
/// Used to turn a rejected permission identifier into an actionable build error. Returns
/// `None` when no candidate clears [`SUGGESTION_CONFIDENCE_THRESHOLD`], so unrelated typos
/// do not get a misleading hint.
fn suggest_identifier(input: &str, candidates: &[String]) -> Option<String> {
  let (input_namespace, input_base) = split_identifier(input);
  let input_namespace_known = candidates
    .iter()
    .any(|candidate| split_identifier(candidate).0 == input_namespace);

  // Also try the input with the `allow-` prefix, which is easy to forget.
  let mut queries = vec![(input.to_string(), input_base.to_string())];
  if !input_base.starts_with("allow-") && !input_base.starts_with("deny-") {
    let base = format!("allow-{input_base}");
    let query = match input_namespace {
      Some(namespace) => format!("{namespace}:{base}"),
      None => base.clone(),
    };
    queries.push((query, base));
  }

  let mut best_confidence = 0.0;
  let mut best_match: Option<&String> = None;

  for (query, query_base) in &queries {
    let query_parts: Vec<&str> = query_base.split('-').collect();

    for candidate in candidates {
      if candidate == input {
        continue;
      }

      let (candidate_namespace, candidate_base) = split_identifier(candidate);

      if !namespaces_match(input_namespace, candidate_namespace, input_namespace_known) {
        continue;
      }

      if !base_components_match(&query_parts, candidate_base) {
        continue;
      }

      let confidence = strsim::jaro_winkler(query, candidate);
      let edit_similarity = strsim::normalized_levenshtein(query, candidate);

      // Jaro-Winkler alone overvalues shared prefixes.
      if confidence >= SUGGESTION_CONFIDENCE_THRESHOLD
        && edit_similarity >= SUGGESTION_CONFIDENCE_THRESHOLD
        && confidence > best_confidence
      {
        best_confidence = confidence;
        best_match = Some(candidate);
      }
    }
  }

  best_match.cloned()
}

#[cfg(test)]
mod tests {
  use super::suggest_identifier;

  fn candidates() -> Vec<String> {
    [
      "fs:allow-read-text-file",
      "fs:allow-write-text-file",
      "fs:default",
      "core:default",
      "core:event:allow-listen",
    ]
    .into_iter()
    .map(String::from)
    .collect()
  }

  #[test]
  fn suggests_on_missing_trailing_character() {
    assert_eq!(
      suggest_identifier("fs:allow-read-text-fil", &candidates()).as_deref(),
      Some("fs:allow-read-text-file")
    );
  }

  #[test]
  fn suggests_nearest_candidate_for_typo() {
    assert_eq!(
      suggest_identifier("fs:allow-read-text-fiel", &candidates()).as_deref(),
      Some("fs:allow-read-text-file")
    );
  }

  #[test]
  fn picks_the_closest_candidate() {
    let candidates: Vec<String> = ["core:event:allow-listen", "core:event:allow-unlisten"]
      .into_iter()
      .map(String::from)
      .collect();
    assert_eq!(
      suggest_identifier("core:event:allow-listenx", &candidates).as_deref(),
      Some("core:event:allow-listen")
    );
  }

  #[test]
  fn no_suggestion_for_read_write_mismatch() {
    let c: Vec<String> = ["fs:allow-write-text-file"]
      .into_iter()
      .map(String::from)
      .collect();
    assert_eq!(suggest_identifier("fs:allow-read-text-file", &c), None);
  }

  #[test]
  fn no_suggestion_for_listen_unlisten_mismatch() {
    let c: Vec<String> = ["core:event:allow-unlisten"]
      .into_iter()
      .map(String::from)
      .collect();
    assert_eq!(suggest_identifier("core:event:allow-listen", &c), None);
  }

  #[test]
  fn suggests_transposed_letters_in_action() {
    let c: Vec<String> = ["core:event:allow-listen"]
      .into_iter()
      .map(String::from)
      .collect();
    assert_eq!(
      suggest_identifier("core:event:allow-lisetn", &c).as_deref(),
      Some("core:event:allow-listen")
    );
  }

  #[test]
  fn no_suggestion_for_different_hyphenation() {
    let c: Vec<String> = ["fs:allow-read-text-file"]
      .into_iter()
      .map(String::from)
      .collect();
    assert_eq!(suggest_identifier("fs:allow-readtext-file", &c), None);
  }

  #[test]
  fn short_action_components_must_match_exactly() {
    let c: Vec<String> = ["core:window:allow-in"]
      .into_iter()
      .map(String::from)
      .collect();
    assert_eq!(suggest_identifier("core:window:allow-on", &c), None);
  }

  #[test]
  fn no_suggestion_for_totally_different_identifier() {
    assert_eq!(suggest_identifier("totally-unrelated", &candidates()), None);
    assert_eq!(suggest_identifier("", &candidates()), None);
  }

  #[test]
  fn no_suggestion_for_incomplete_permission() {
    assert_eq!(suggest_identifier("fs:allow", &candidates()), None);
    assert_eq!(suggest_identifier("fs:allow-foo", &candidates()), None);
  }

  #[test]
  fn no_suggestion_for_different_namespace() {
    assert_eq!(
      suggest_identifier("xx:allow-read-text-file", &candidates()),
      None
    );
  }

  #[test]
  fn suggests_for_namespace_typo() {
    let c: Vec<String> = ["core:window:allow-set-title", "dialog:default"]
      .into_iter()
      .map(String::from)
      .collect();
    assert_eq!(
      suggest_identifier("core:windw:allow-set-title", &c).as_deref(),
      Some("core:window:allow-set-title")
    );
    assert_eq!(
      suggest_identifier("dialgo:default", &c).as_deref(),
      Some("dialog:default")
    );
  }

  #[test]
  fn no_namespace_typo_suggestion_when_namespace_exists() {
    let c: Vec<String> = ["core:window:allow-close", "core:webview:allow-print"]
      .into_iter()
      .map(String::from)
      .collect();
    assert_eq!(suggest_identifier("core:window:allow-print", &c), None);
  }

  #[test]
  fn suggests_missing_allow_prefix() {
    let c: Vec<String> = [
      "core:window:allow-set-title",
      "core:window:deny-set-title",
      "allow-echo",
    ]
    .into_iter()
    .map(String::from)
    .collect();
    assert_eq!(
      suggest_identifier("core:window:set-title", &c).as_deref(),
      Some("core:window:allow-set-title")
    );
    assert_eq!(
      suggest_identifier("core:window:set-titel", &c).as_deref(),
      Some("core:window:allow-set-title")
    );
    assert_eq!(
      suggest_identifier("echo", &c).as_deref(),
      Some("allow-echo")
    );
  }

  #[test]
  fn no_suggestion_without_candidates() {
    assert_eq!(suggest_identifier("fs:allow-read", &[]), None);
  }

  #[test]
  fn exact_match_is_never_suggested() {
    assert_eq!(
      suggest_identifier("fs:default", &candidates()),
      None,
      "an exact match is not a misspelling, so nothing should be suggested"
    );
  }
}