autocomplete: Match user results by email match, and rank by match quality

chrisbobbe · chrisbobbe · commit 4a6b3d8387f2 · 2025-07-30T17:26:08.000-07:00
Fixes zulip#236.
diff --git a/lib/model/autocomplete.dart b/lib/model/autocomplete.dart
@@ -744,6 +744,25 @@ enum NameMatchQuality {
   wordPrefixes,
 }
 
+/// The match quality of a [UserStore.userDisplayEmail]
+/// to a mention autocomplete query.
+///
+/// All matches are case-insensitive.
+enum EmailMatchQuality {
+  /// The query starts with the email's "local part", then "@",
+  /// then a nonempty prefix of the "domain".
+  ///
+  /// For example, the query "email@e" matches "email@example.com" this way,
+  /// but "email" and "email@" do not.
+  localPartExactAndDomainPrefix,
+
+  /// The query is the email's "local part" optionally followed by "@".
+  localPartExact,
+
+  /// The email starts with the query.
+  prefix,
+}
+
 /// Any autocomplete query in the compose box's content input.
 abstract class ComposeAutocompleteQuery extends AutocompleteQuery {
   ComposeAutocompleteQuery(super.raw);
@@ -789,15 +808,19 @@ class MentionAutocompleteQuery extends ComposeAutocompleteQuery {
     if (store.isUserMuted(user.userId)) return null;
 
     final cache = store.autocompleteViewManager.autocompleteDataCache;
-    // TODO(#236) test email too, not just name
     final nameMatchQuality = _matchName(
       lowercaseName: cache.lowercaseNameForUser(user),
       lowercaseNameWords: cache.lowercaseNameWordsForUser(user));
-    if (nameMatchQuality == null) return null;
+    EmailMatchQuality? emailMatchQuality;
+    if (nameMatchQuality == null) {
+      emailMatchQuality = _matchEmail(user, cache);
+      if (emailMatchQuality == null) return null;
+    }
 
     return UserMentionAutocompleteResult(
       userId: user.userId,
-      rank: _rankUserResult(user, nameMatchQuality: nameMatchQuality));
+      rank: _rankUserResult(user,
+        nameMatchQuality: nameMatchQuality, emailMatchQuality: emailMatchQuality));
   }
 
   NameMatchQuality? _matchName({
@@ -825,6 +848,53 @@ class MentionAutocompleteQuery extends ComposeAutocompleteQuery {
     return null;
   }
 
+  EmailMatchQuality? _matchEmail(User user, AutocompleteDataCache cache) {
+    final lowercaseEmail = cache.lowercaseEmailForUser(user);
+    if (lowercaseEmail == null) return null; // Email not known
+
+    final userEmailParts = cache.lowercaseEmailPartsForUser(user);
+    if (userEmailParts == null) { // TODO(log)?
+      // Email has unexpected shape; just do a simple match
+      return lowercaseEmail.startsWith(_lowercase)
+        ? EmailMatchQuality.prefix
+        : null;
+    }
+
+    final (localPart, domain) = userEmailParts;
+
+    int localPartMatchLength = 0;
+    while (
+      localPartMatchLength < localPart.length && localPartMatchLength < _lowercase.length
+      && localPart[localPartMatchLength] == _lowercase[localPartMatchLength]
+    ) {
+      localPartMatchLength++;
+    }
+
+    final reachedLocalPartEnd = localPartMatchLength == localPart.length;
+    bool reachedQueryEnd = localPartMatchLength == _lowercase.length;
+    switch ((reachedLocalPartEnd, reachedQueryEnd)) {
+      case (false, false): return null;
+      case (false, true ): return EmailMatchQuality.prefix;
+      case (true,  true ): return EmailMatchQuality.localPartExact;
+      case (true,  false):
+        assert(_lowercase.length >= localPart.length);
+        if (_lowercase[localPart.length] != '@') return null;
+        if (_lowercase.length == localPart.length + 1) {
+          // // Query matches the local part plus just '@'.
+          return EmailMatchQuality.localPartExact;
+        }
+        // Proceed to check the domain
+    }
+
+    int i = 0; // index in domain
+    for (int j = localPart.length + 1; j < _lowercase.length; j++) {
+      if (i >= domain.length) return null;
+      if (_lowercase[j] != domain[i]) return null;
+      i++;
+    }
+    return EmailMatchQuality.localPartExactAndDomainPrefix;
+  }
+
   /// A measure of a wildcard result's quality in the context of the query,
   /// from 0 (best) to one less than [_numResultRanks].
   ///
@@ -835,17 +905,28 @@ class MentionAutocompleteQuery extends ComposeAutocompleteQuery {
   /// from 0 (best) to one less than [_numResultRanks].
   ///
   /// See also [_rankWildcardResult].
-  static int _rankUserResult(User user, {required NameMatchQuality nameMatchQuality}) {
-    return switch (nameMatchQuality) {
-      NameMatchQuality.exact =>        1,
-      NameMatchQuality.totalPrefix =>  2,
-      NameMatchQuality.wordPrefixes => 3,
+  static int _rankUserResult(User user, {
+    required NameMatchQuality? nameMatchQuality,
+    required EmailMatchQuality? emailMatchQuality,
+  }) {
+    if (nameMatchQuality != null) {
+      return switch (nameMatchQuality) {
+        NameMatchQuality.exact =>        1,
+        NameMatchQuality.totalPrefix =>  2,
+        NameMatchQuality.wordPrefixes => 3,
+      };
+    }
+    assert(emailMatchQuality != null);
+    return switch (emailMatchQuality!) {
+      EmailMatchQuality.localPartExactAndDomainPrefix => 4,
+      EmailMatchQuality.localPartExact =>                5,
+      EmailMatchQuality.prefix =>                        6,
     };
   }
 
   /// The number of possible values returned by
   /// [_rankWildcardResult] and [_rankUserResult].
-  static const _numResultRanks = 4;
+  static const _numResultRanks = 7;
 
   @override
   String toString() {
@@ -892,9 +973,45 @@ class AutocompleteDataCache {
     return _lowercaseNameWordsByUser[user.userId] ??= lowercaseNameForUser(user).split(' ');
   }
 
+  final Map<int, String?> _lowercaseEmailsByUser = {};
+
+  /// The lowercase `deliveryEmail` of [user], or null if that's null.
+  String? lowercaseEmailForUser(User user) {
+    return _lowercaseEmailsByUser[user.userId] ??= user.deliveryEmail?.toLowerCase();
+  }
+
+  final Map<int, (String localPart, String domain)?> _lowercaseEmailPartsByUser = {};
+
+  /// The [lowercaseEmailForUser] split by the single "@" if it has that shape,
+  /// else null.
+  (String localPart, String domain)? lowercaseEmailPartsForUser(User user) {
+    // Optimization: use containsKey to check the cache, instead of operator [],
+    // because `null` is a valid value that can take some string-computation
+    // to compute (on unexpected email strings with multiple "@"s).
+    return _lowercaseEmailPartsByUser.containsKey(user.userId)
+      ? _lowercaseEmailPartsByUser[user.userId]
+      : (_lowercaseEmailPartsByUser[user.userId] = _computeLowercaseEmailPartsForUser(user));
+  }
+
+  /// Whether to throw an [AssertionError] on [lowercaseEmailPartsForUser]'s
+  /// cache-misses. Useful for testing.
+  bool debugErrorOnComputeEmailParts = false;
+
+  (String localPart, String domain)? _computeLowercaseEmailPartsForUser(User user) {
+    assert(!debugErrorOnComputeEmailParts);
+
+    final lowercaseEmail = lowercaseEmailForUser(user);
+    if (lowercaseEmail == null) return null;
+    final split = lowercaseEmail.split('@');
+    if (split.length != 2) return null;
+    return (split[0], split[1]);
+  }
+
   void invalidateUser(int userId) {
     _lowercaseNamesByUser.remove(userId);
     _lowercaseNameWordsByUser.remove(userId);
+    _lowercaseEmailsByUser.remove(userId);
+    _lowercaseEmailPartsByUser.remove(userId);
   }
 }
 
@@ -947,6 +1064,9 @@ sealed class MentionAutocompleteResult extends ComposeAutocompleteResult {
   // Behavior we have that web doesn't and might like to follow:
   // - A "word-prefixes" match quality on user names:
   //   see [NameMatchQuality.wordPrefixes], which we rank on.
+  // - Two email match qualities when the query matches the "local part";
+  //   see [EmailMatchQuality.localPartExactAndDomainPrefix] and
+  //   [EmailMatchQuality.localPartExact], which we rank on.
   //
   // Behavior web has that seems undesired, which we don't plan to follow:
   // - Ranking humans above bots, even when the bots have higher relevance
@@ -957,6 +1077,12 @@ sealed class MentionAutocompleteResult extends ComposeAutocompleteResult {
   //   special rank when the whole query appears contiguously
   //   right after a word-boundary character.
   //   Our [NameMatchQuality.wordPrefixes] seems smarter.
+  // - An "exact" match quality on emails: probably not worth its complexity.
+  //   Emails are much more uniform in their endings than users' names are,
+  //   so [EmailMatchQuality.localPartExactAndDomainPrefix] should be adequate.
+  //   (If I've typed "email@example.co", that'll probably be the only result.
+  //   There might be an "email@example.com", and an "exact" match would
+  //   downrank that, but still that's just two items to scan throug.)
   // - A "word-boundary" match quality on user emails:
   //   "words" is a wrong abstraction when matching on emails.
   // - Ranking some case-sensitive matches differently from case-insensitive
diff --git a/test/model/autocomplete_test.dart b/test/model/autocomplete_test.dart
@@ -263,6 +263,45 @@ void main() {
     doTest('。~:^', emoji('')); doTest('。~:a^', emoji('a'));
   });
 
+  group('AutocompleteDataCache', () {
+    // TODO test user full-name data
+
+    test('lowercaseEmailPartsForUser.debugErrorOnComputeEmailParts works', () {
+      final cache = AutocompleteDataCache()
+        ..debugErrorOnComputeEmailParts = true;
+
+      check(() => cache.lowercaseEmailPartsForUser(eg.user())).throws<AssertionError>();
+    });
+
+    test('lowercaseEmailPartsForUser: non-null deliveryEmail', () {
+      final cache = AutocompleteDataCache();
+
+      final user = eg.user(deliveryEmail: 'Email@example.com');
+      final result = cache.lowercaseEmailPartsForUser(user);
+      cache.debugErrorOnComputeEmailParts = true; // (this flag is tested above)
+      final cachedResult = cache.lowercaseEmailPartsForUser(user);
+      check(cachedResult)..identicalTo(result)..equals(('email', 'example.com'));
+    });
+
+    test('lowercaseEmailPartsForUser: null deliveryEmail', () {
+      final cache = AutocompleteDataCache();
+
+      final user = eg.user(deliveryEmail: null);
+      check(cache.lowercaseEmailPartsForUser(user)).isNull();
+      cache.debugErrorOnComputeEmailParts = true; // (this flag is tested above)
+      check(cache.lowercaseEmailPartsForUser(user)).isNull();
+    });
+
+    test('lowercaseEmailPartsForUser: non-null deliveryEmail but with multiple "@"s', () {
+      final cache = AutocompleteDataCache();
+
+      final user = eg.user(deliveryEmail: 'Email@example@com');
+      check(cache.lowercaseEmailPartsForUser(user)).isNull();
+      cache.debugErrorOnComputeEmailParts = true; // (this flag is tested above)
+      check(cache.lowercaseEmailPartsForUser(user)).isNull();
+    });
+  });
+
   test('MentionAutocompleteView misc', () async {
     const narrow = ChannelNarrow(1);
     final store = eg.store();
@@ -1037,14 +1076,46 @@ void main() {
       checkPrecedes('so m', user1, user2);
     });
 
+    test('email matched case-insensitively', () {
+      final user1 = eg.user(deliveryEmail: 'email@example.com');
+      final user2 = eg.user(deliveryEmail: 'EmAiL@ExAmPlE.com');
+
+      checkSameRank('email@example.com', user1, user2); // exact
+      checkSameRank('email@e',           user1, user2); // local-part-exact-and-domain-prefix
+      checkSameRank('email@',            user1, user2); // local-part-exact
+      checkSameRank('email',             user1, user2); // local-part-exact
+      checkSameRank('ema',               user1, user2); // prefix
+    });
+
+    test('email matching: when email has unexpected shape, no crash; just do a prefix match', () {
+      final user1 = eg.user(deliveryEmail: 'something weird');
+      final user2 = eg.user(deliveryEmail: 'something@example.com');
+      checkSameRank('some', user1, user2);
+    });
+
+    test('email match: local-part-exact-and-domain-prefix over local-part-exact', () {
+      final user = eg.user(deliveryEmail: 'email@zulip.com');
+      check(rankOf('email@z', user)!).isLessThan(rankOf('email', user)!);
+    });
+
+    test('email match: local-part-exact over prefix', () {
+      final user1 = eg.user(deliveryEmail: 'email@zulip.com');
+      final user2 = eg.user(deliveryEmail: 'emailaddress@example.com');
+
+      checkPrecedes('email', user1, user2);
+    });
+
     test('full list of ranks', () {
-      final user1 = eg.user(fullName: 'some user');
+      final user1 = eg.user(fullName: 'some user', deliveryEmail: 'email@example.com');
       check([
         rankOf('', WildcardMentionOption.all), // wildcard
         rankOf('some user', user1),            // user, exact name match
         rankOf('some us', user1),              // user, total-prefix name match
         rankOf('so us', user1),                // user, word-prefixes name match
-      ]).deepEquals([0, 1, 2, 3]);
+        rankOf('email@e', user1),              // user, local-part-exact-domain-prefix email match
+        rankOf('email', user1),                // user, local-part-exact email match
+        rankOf('emai', user1),                 // user, prefix email match
+      ]).deepEquals([0, 1, 2, 3, 4, 5, 6]);
     });
   });
 
