Skip to content

Offline, privacy-first grammar checker. Fast, open-source, Rust-powered

perf(spell): skip redundant lowercase DFA search in FstDictionary (#3025)

Kacper Kuczkowski0fe03c35793b
diff --git a/harper-core/Cargo.toml b/harper-core/Cargo.toml
index 630d4ea43..b49bce655 100644
--- a/harper-core/Cargo.toml
+++ b/harper-core/Cargo.toml
@@ -48,6 +48,10 @@ rayon = "1.11.0"
name = "parse_essay"
harness = false
+[[bench]]
+name = "spellcheck"
+harness = false
+
[features]
default = ["thesaurus"]
concurrent = []
diff --git a/harper-core/benches/misspelled_words/capitalized.md b/harper-core/benches/misspelled_words/capitalized.md
new file mode 100644
index 000000000..1ee4df230
--- /dev/null
+++ b/harper-core/benches/misspelled_words/capitalized.md
@@ -0,0 +1,28 @@
+Siplest
+Des
+Histry
+Couse
+Hman
+Boh
+Nclear
+Eploration
+Conciousness
+Recieved
+Thier
+Definately
+Seperate
+Occured
+Accomodate
+Embarass
+Enviroment
+Goverment
+Independant
+Restarant
+Knowlege
+Wierd
+Acheive
+Beleive
+Calender
+Rythm
+Yeild
+Buisness
diff --git a/harper-core/benches/misspelled_words/lowercase.md b/harper-core/benches/misspelled_words/lowercase.md
new file mode 100644
index 000000000..587532327
--- /dev/null
+++ b/harper-core/benches/misspelled_words/lowercase.md
@@ -0,0 +1,28 @@
+siplest
+des
+histry
+couse
+hman
+boh
+nclear
+eploration
+conciousness
+recieved
+thier
+definately
+seperate
+occured
+accomodate
+embarass
+enviroment
+goverment
+independant
+restarant
+knowlege
+wierd
+acheive
+beleive
+calender
+rythm
+yeild
+buisness
diff --git a/harper-core/benches/misspelled_words/mixed.md b/harper-core/benches/misspelled_words/mixed.md
new file mode 100644
index 000000000..b28b25344
--- /dev/null
+++ b/harper-core/benches/misspelled_words/mixed.md
@@ -0,0 +1,32 @@
+siplest
+des
+histry
+couse
+hman
+boh
+nclear
+eploration
+conciousness
+recieved
+thier
+definately
+seperate
+occured
+accomodate
+embarass
+enviroment
+goverment
+independant
+restarant
+knowlege
+wierd
+acheive
+beleive
+calender
+rythm
+yeild
+buisness
+Recieved
+Definately
+Seperate
+Goverment
diff --git a/harper-core/benches/spellcheck.rs b/harper-core/benches/spellcheck.rs
new file mode 100644
index 000000000..a092a07dc
--- /dev/null
+++ b/harper-core/benches/spellcheck.rs
@@ -0,0 +1,178 @@
+use criterion::{
+ BenchmarkGroup, Criterion, Throughput, criterion_group, criterion_main, measurement::WallTime,
+};
+use harper_core::spell::{Dictionary, FstDictionary, MergedDictionary, suggest_correct_spelling};
+use std::hint::black_box;
+
+static ESSAY: &str = include_str!("./essay.md");
+
+// misspelled_words/: one word per line, no comments or markup.
+// Distribution mirrors natural text to avoid skewing results:
+// - Mostly edit distance 1-2 (common typos), a few distance 3
+// - Mix of short, medium, and long words
+// The essay.md bench covers realistic prose;
+// these lists complement it with realistic misspelling patterns.
+static MISSPELLED_MIXED: &str = include_str!("./misspelled_words/mixed.md");
+static MISSPELLED_LOWERCASE: &str = include_str!("./misspelled_words/lowercase.md");
+static MISSPELLED_CAPITALIZED: &str = include_str!("./misspelled_words/capitalized.md");
+
+type WordList = Vec<Vec<char>>;
+type WordCase<'a> = (&'static str, &'a [Vec<char>]);
+
+/// Pulls words out of the essay sample.
+///
+/// This gives the benchmark a realistic prose word stream while trimming
+/// punctuation so we measure spell-check work, not punctuation noise.
+fn essay_words() -> WordList {
+ ESSAY
+ .split_whitespace()
+ .map(|w| w.trim_matches(|c: char| !c.is_alphabetic()))
+ .filter(|w| !w.is_empty())
+ .map(|w| w.chars().collect())
+ .collect()
+}
+
+/// Loads a word list from a static string (one word per line).
+fn load_word_list(source: &str) -> WordList {
+ source
+ .lines()
+ .filter(|l| !l.is_empty())
+ .map(|w| w.chars().collect())
+ .collect()
+}
+
+/// Returns the shared typo cases used by multiple benchmark groups.
+///
+/// Keeping this in one place makes it easier to add, remove, or rename cases
+/// without updating each benchmark group by hand.
+fn typo_cases<'a>(
+ mixed: &'a WordList,
+ lowercase: &'a WordList,
+ capitalized: &'a WordList,
+) -> [WordCase<'a>; 3] {
+ [
+ ("misspelled_mixed", mixed.as_slice()),
+ ("misspelled_lowercase", lowercase.as_slice()),
+ ("misspelled_capitalized", capitalized.as_slice()),
+ ]
+}
+
+/// Tells Criterion how many words a benchmark case processes.
+///
+/// This makes the output easier to read because results are tied to the number
+/// of words handled, not just to one pass over a particular file.
+fn set_word_throughput(group: &mut BenchmarkGroup<'_, WallTime>, words: &[Vec<char>]) {
+ group.throughput(Throughput::Elements(words.len() as u64));
+}
+
+/// Benchmarks a spell-check operation on a word list.
+///
+/// This contains the shared benchmark loop used by all spell-check cases. It
+/// also adds up result counts so the compiler cannot treat returned values as
+/// unused and optimize too aggressively.
+fn bench_word_list<F>(
+ group: &mut BenchmarkGroup<'_, WallTime>,
+ name: &str,
+ words: &[Vec<char>],
+ mut run: F,
+) where
+ F: FnMut(&[char]) -> usize,
+{
+ set_word_throughput(group, words);
+ group.bench_function(name, |b| {
+ b.iter(|| {
+ let mut total_matches = 0usize;
+ for word in words {
+ total_matches += run(black_box(word.as_slice()));
+ }
+ total_matches
+ });
+ });
+}
+
+/// Benchmarks direct `FstDictionary::fuzzy_match` calls on a word list.
+///
+/// This is the most direct way to measure changes in the FST spell-check path.
+fn bench_fuzzy_match(group: &mut BenchmarkGroup<'_, WallTime>, name: &str, words: &[Vec<char>]) {
+ let dict = FstDictionary::curated();
+
+ bench_word_list(group, name, words, |word| {
+ black_box(dict.fuzzy_match(word, 3, 200)).len()
+ });
+}
+
+/// Benchmarks `suggest_correct_spelling` on a word list.
+///
+/// This measures the higher-level suggestion path on top of `fuzzy_match`,
+/// including result ordering, so we can see whether the lower-level win still
+/// shows up after the extra suggestion work.
+fn bench_suggest_correct_spelling(
+ group: &mut BenchmarkGroup<'_, WallTime>,
+ name: &str,
+ words: &[Vec<char>],
+) {
+ let dict = FstDictionary::curated();
+
+ bench_word_list(group, name, words, |word| {
+ black_box(suggest_correct_spelling(word, 200, 3, &*dict)).len()
+ });
+}
+
+/// Benchmarks fuzzy matching through a single-child `MergedDictionary`.
+///
+/// This checks the extra wrapper layer around the underlying dictionary call.
+/// It is intentionally a single-child setup, so it measures wrapper cost more
+/// than realistic merged-dictionary behavior.
+fn bench_fuzzy_match_merged_dict_single_child(
+ group: &mut BenchmarkGroup<'_, WallTime>,
+ name: &str,
+ words: &[Vec<char>],
+) {
+ let dict = FstDictionary::curated();
+ let mut merged = MergedDictionary::new();
+ merged.add_dictionary(dict);
+
+ bench_word_list(group, name, words, |word| {
+ black_box(merged.fuzzy_match(word, 3, 200)).len()
+ });
+}
+
+/// Registers the spell-check benchmarks and word-list splits.
+///
+/// The mixed typo benchmarks keep continuity with older results, while the
+/// lowercase and capitalized versions make the case-based effect easier to see
+/// instead of averaging it away. Each group also reports throughput in words,
+/// which makes the output easier to compare if the input lists change later.
+pub fn criterion_benchmark(c: &mut Criterion) {
+ let essay = essay_words();
+ let misspelled_mixed = load_word_list(MISSPELLED_MIXED);
+ let misspelled_lowercase = load_word_list(MISSPELLED_LOWERCASE);
+ let misspelled_capitalized = load_word_list(MISSPELLED_CAPITALIZED);
+ let cases = typo_cases(
+ &misspelled_mixed,
+ &misspelled_lowercase,
+ &misspelled_capitalized,
+ );
+
+ let mut fuzzy_match_group = c.benchmark_group("fuzzy_match");
+ bench_fuzzy_match(&mut fuzzy_match_group, "essay", &essay);
+ for &(name, words) in &cases {
+ bench_fuzzy_match(&mut fuzzy_match_group, name, words);
+ }
+ fuzzy_match_group.finish();
+
+ let mut suggest_group = c.benchmark_group("suggest_correct_spelling");
+ for &(name, words) in &cases {
+ bench_suggest_correct_spelling(&mut suggest_group, name, words);
+ }
+ suggest_group.finish();
+
+ let mut merged_group = c.benchmark_group("fuzzy_match_merged_dict_single_child");
+ for &(name, words) in &cases {
+ bench_fuzzy_match_merged_dict_single_child(&mut merged_group, name, words);
+ }
+ merged_group.finish();
+}
+
+criterion_group!(benches, criterion_benchmark);
+criterion_main!(benches);
diff --git a/harper-core/src/spell/fst_dictionary.rs b/harper-core/src/spell/fst_dictionary.rs
index c44dd716d..41e306d97 100644
--- a/harper-core/src/spell/fst_dictionary.rs
+++ b/harper-core/src/spell/fst_dictionary.rs
@@ -112,6 +112,19 @@ fn stream_distances_vec(stream: &mut StreamWithState<&DFA>, dfa: &DFA) -> Vec<(u
word_index_pairs
}
+/// Merges index-distance pairs, keeping the smallest distance for each word.
+fn merge_best_distances(
+ best_distances: &mut HashMap<u64, u8>,
+ distances: impl IntoIterator<Item = (u64, u8)>,
+) {
+ for (idx, dist) in distances {
+ best_distances
+ .entry(idx)
+ .and_modify(|existing| *existing = (*existing).min(dist))
+ .or_insert(dist);
+ }
+}
+
impl Dictionary for FstDictionary {
fn contains_word(&self, word: &[char]) -> bool {
self.mutable_dict.contains_word(word)
@@ -137,32 +150,35 @@ impl Dictionary for FstDictionary {
) -> Vec<FuzzyMatchResult<'_>> {
let misspelled_word_charslice = word.normalized();
let misspelled_word_string = misspelled_word_charslice.to_string();
+ let misspelled_lower = misspelled_word_string.to_lowercase();
+ let is_already_lower = misspelled_lower == misspelled_word_string;
// Actual FST search
let dfa = build_dfa(max_distance, &misspelled_word_string);
- let dfa_lowercase = build_dfa(max_distance, &misspelled_word_string.to_lowercase());
let mut word_indexes_stream = self.word_map.search_with_state(&dfa).into_stream();
- let mut word_indexes_lowercase_stream = self
- .word_map
- .search_with_state(&dfa_lowercase)
- .into_stream();
-
let upper_dists = stream_distances_vec(&mut word_indexes_stream, &dfa);
- let lower_dists = stream_distances_vec(&mut word_indexes_lowercase_stream, &dfa_lowercase);
// Merge the two results, keeping the smallest distance when both DFAs match.
// The uppercase and lowercase searches can return different result counts, so
// we can't simply zip the vectors without losing matches.
- let mut merged = Vec::with_capacity(upper_dists.len().max(lower_dists.len()));
let mut best_distances = HashMap::<u64, u8>::new();
- for (idx, dist) in upper_dists.into_iter().chain(lower_dists.into_iter()) {
- best_distances
- .entry(idx)
- .and_modify(|existing| *existing = (*existing).min(dist))
- .or_insert(dist);
+ merge_best_distances(&mut best_distances, upper_dists);
+
+ // Only build the lowercase DFA when the query is not already lowercase.
+ if !is_already_lower {
+ let dfa_lowercase = build_dfa(max_distance, &misspelled_lower);
+ let mut word_indexes_lowercase_stream = self
+ .word_map
+ .search_with_state(&dfa_lowercase)
+ .into_stream();
+ let lower_dists =
+ stream_distances_vec(&mut word_indexes_lowercase_stream, &dfa_lowercase);
+
+ merge_best_distances(&mut best_distances, lower_dists);
}
+ let mut merged = Vec::with_capacity(best_distances.len());
for (index, edit_distance) in best_distances {
let (word, metadata) = &self.words[index as usize];
merged.push(FuzzyMatchResult {
@@ -235,10 +251,39 @@ mod tests {
use itertools::Itertools;
use crate::CharStringExt;
- use crate::spell::{Dictionary, WordId};
+ use crate::DictWordMetadata;
+ use crate::spell::{Dictionary, MutableDictionary, WordId};
use super::FstDictionary;
+ fn test_dictionaries(words: &[&str]) -> (MutableDictionary, FstDictionary) {
+ let mut mutable = MutableDictionary::new();
+
+ for word in words {
+ mutable.append_word_str(word, DictWordMetadata::default());
+ }
+
+ let fst = FstDictionary::from(mutable.clone());
+
+ (mutable, fst)
+ }
+
+ fn fuzzy_matches<D: Dictionary + ?Sized>(
+ dict: &D,
+ word: &str,
+ max_distance: u8,
+ max_results: usize,
+ ) -> Vec<(String, u8)> {
+ let mut matches = dict
+ .fuzzy_match_str(word, max_distance, max_results)
+ .into_iter()
+ .map(|result| (result.word.iter().collect::<String>(), result.edit_distance))
+ .collect_vec();
+
+ matches.sort_unstable_by(|a, b| a.1.cmp(&b.1).then_with(|| a.0.cmp(&b.0)));
+ matches
+ }
+
#[test]
fn damerau_transposition_costs_one() {
let lev_automata =
@@ -387,4 +432,53 @@ mod tests {
WordId::from_word_str("quick")
);
}
+
+ #[test]
+ fn lowercase_fuzzy_match_matches_mutable_dictionary() {
+ let (mutable, fst) =
+ test_dictionaries(&["spelling", "spilling", "selling", "smelling", "shelling"]);
+
+ let mutable_results = fuzzy_matches(&mutable, "speling", 3, 10);
+ let fst_results = fuzzy_matches(&fst, "speling", 3, 10);
+
+ assert_eq!(fst_results, mutable_results);
+ assert_eq!(fst_results.first(), Some(&(String::from("spelling"), 1)));
+ }
+
+ #[test]
+ fn capitalized_fuzzy_match_matches_mutable_dictionary() {
+ let (mutable, fst) =
+ test_dictionaries(&["spelling", "spilling", "selling", "smelling", "shelling"]);
+
+ let mutable_results = fuzzy_matches(&mutable, "Speling", 3, 10);
+ let fst_results = fuzzy_matches(&fst, "Speling", 3, 10);
+
+ assert_eq!(fst_results, mutable_results);
+ assert_eq!(fst_results.first(), Some(&(String::from("spelling"), 1)));
+ }
+
+ #[test]
+ fn uppercase_fuzzy_match_matches_mutable_dictionary() {
+ let (mutable, fst) =
+ test_dictionaries(&["spelling", "spilling", "selling", "smelling", "shelling"]);
+
+ let mutable_results = fuzzy_matches(&mutable, "SPELING", 3, 10);
+ let fst_results = fuzzy_matches(&fst, "SPELING", 3, 10);
+
+ assert_eq!(fst_results, mutable_results);
+ assert_eq!(fst_results.first(), Some(&(String::from("spelling"), 1)));
+ }
+
+ #[test]
+ fn query_casing_produces_the_same_fuzzy_matches() {
+ let (_, fst) =
+ test_dictionaries(&["spelling", "spilling", "selling", "smelling", "shelling"]);
+
+ let lowercase = fuzzy_matches(&fst, "speling", 3, 10);
+ let capitalized = fuzzy_matches(&fst, "Speling", 3, 10);
+ let uppercase = fuzzy_matches(&fst, "SPELING", 3, 10);
+
+ assert_eq!(lowercase, capitalized);
+ assert_eq!(lowercase, uppercase);
+ }
}