feat: enhance co-author parsing with advanced email resolution

- Add support for extracting usernames from @github.com email addresses
- Integrate GitHub Search Users API to resolve arbitrary emails to usernames
- Add fallback behavior when API calls fail or return no results
- Thread github_connection parameter through co-author parsing functions
- Remove unused existing_usernames parameter from get_coauthor_contributors
- Update all function signatures and test cases with new parameters
- Improve co-author identification from noreply, GitHub, and external emails

This significantly improves co-author recognition by automatically resolving
multiple email formats to GitHub usernames, providing more accurate contributor
attribution and better coverage of collaborative contributions.

Signed-off-by: Zack Koppert <[email protected]>

Author: zkoppert

contributors.py

@@ -143,7 +143,12 @@ def get_all_contributors(
     if repos:
         for repo in repos:
             repo_contributors = get_contributors(
-                repo, start_date, end_date, ghe, acknowledge_coauthors
+                repo,
+                start_date,
+                end_date,
+                ghe,
+                acknowledge_coauthors,
+                github_connection,
             )
             if repo_contributors:
                 all_contributors.append(repo_contributors)
@@ -154,18 +159,22 @@ def get_all_contributors(
     return all_contributors
 
 
-def get_coauthors_from_message(commit_message: str) -> List[str]:
+def get_coauthors_from_message(
+    commit_message: str, github_connection: object = None
+) -> List[str]:
     """
     Extract co-author identifiers from a commit message.
 
     Co-authored-by trailers follow the format:
     Co-authored-by: Name <email>
 
     For GitHub noreply emails ([email protected]), extracts the username.
-    For other emails, extracts the full email address.
+    For @github.com emails, extracts the username (part before @).
+    For other emails, uses GitHub Search Users API to find the username, or falls back to email.
 
     Args:
         commit_message (str): The commit message to parse
+        github_connection (object): The authenticated GitHub connection object from PyGithub
 
     Returns:
         List[str]: List of co-author identifiers (GitHub usernames or email addresses)
@@ -183,9 +192,28 @@ def get_coauthors_from_message(commit_message: str) -> List[str]:
         if noreply_match:
             # For GitHub noreply emails, extract just the username
             identifiers.append(noreply_match.group(2))
+        elif email.endswith("@github.com"):
+            # For @github.com emails, extract the username (part before @)
+            username = email.split("@")[0]
+            identifiers.append(username)
         else:
-            # For other emails, use the full email address
-            identifiers.append(email)
+            # For other emails, try to find GitHub username using Search Users API
+            if github_connection:
+                try:
+                    # Search for users by email
+                    search_result = github_connection.search_users(f"email:{email}")
+                    if search_result.totalCount > 0:
+                        # Use the first matching user's login
+                        identifiers.append(search_result[0].login)
+                    else:
+                        # If no user found, fall back to email address
+                        identifiers.append(email)
+                except Exception:
+                    # If API call fails, fall back to email address
+                    identifiers.append(email)
+            else:
+                # If no GitHub connection available, use the full email address
+                identifiers.append(email)
     return identifiers
 
 
@@ -195,6 +223,7 @@ def get_contributors(
     end_date: str,
     ghe: str,
     acknowledge_coauthors: bool,
+    github_connection: object,
 ):
     """
     Get contributors from a single repository and filter by start end dates if present.
@@ -205,6 +234,7 @@ def get_contributors(
         end_date (str): The end date of the date range for the contributor list.
         ghe (str): The GitHub Enterprise URL to use for authentication
         acknowledge_coauthors (bool): Whether to acknowledge co-authors from commit messages
+        github_connection (object): The authenticated GitHub connection object from PyGithub
 
     Returns:
         contributors (list): A list of ContributorStats objects
@@ -252,7 +282,11 @@ def get_contributors(
         # Get co-authors from commit messages if enabled
         if acknowledge_coauthors:
             coauthor_contributors = get_coauthor_contributors(
-                repo, start_date, end_date, ghe, contributor_usernames
+                repo,
+                start_date,
+                end_date,
+                ghe,
+                github_connection,
             )
             contributors.extend(coauthor_contributors)
 
@@ -269,7 +303,7 @@ def get_coauthor_contributors(
     start_date: str,
     end_date: str,
     ghe: str,
-    existing_usernames: set,
+    github_connection: object,
 ) -> List[contributor_stats.ContributorStats]:
     """
     Get contributors who were co-authors on commits in the repository.
@@ -279,7 +313,7 @@ def get_coauthor_contributors(
         start_date (str): The start date of the date range for the contributor list.
         end_date (str): The end date of the date range for the contributor list.
         ghe (str): The GitHub Enterprise URL
-        existing_usernames (set): Set of usernames already added as contributors
+        github_connection (object): The authenticated GitHub connection object from PyGithub
 
     Returns:
         List[ContributorStats]: A list of ContributorStats objects for co-authors
@@ -301,10 +335,9 @@ def get_coauthor_contributors(
                 continue
 
             # Extract co-authors from commit message
-            coauthors = get_coauthors_from_message(commit_message)
+            coauthors = get_coauthors_from_message(commit_message, github_connection)
             for username in coauthors:
-                if username not in existing_usernames:
-                    coauthor_counts[username] = coauthor_counts.get(username, 0) + 1
+                coauthor_counts[username] = coauthor_counts.get(username, 0) + 1
 
     except Exception as e:
         print(f"Error getting co-authors for repository: {repo.full_name}")

test_contributors.py

@@ -30,7 +30,7 @@ def test_get_contributors(self, mock_contributor_stats):
         mock_repo.contributors.return_value = [mock_user]
         mock_repo.full_name = "owner/repo"
 
-        get_contributors(mock_repo, "2022-01-01", "2022-12-31", "", False)
+        get_contributors(mock_repo, "2022-01-01", "2022-12-31", "", False, None)
 
         mock_contributor_stats.assert_called_once_with(
             "user",
@@ -81,10 +81,10 @@ def test_get_all_contributors_with_organization(self, mock_get_contributors):
             ],
         )
         mock_get_contributors.assert_any_call(
-            "repo1", "2022-01-01", "2022-12-31", ghe, False
+            "repo1", "2022-01-01", "2022-12-31", ghe, False, mock_github_connection
         )
         mock_get_contributors.assert_any_call(
-            "repo2", "2022-01-01", "2022-12-31", ghe, False
+            "repo2", "2022-01-01", "2022-12-31", ghe, False, mock_github_connection
         )
 
     @patch("contributors.get_contributors")
@@ -130,7 +130,7 @@ def test_get_all_contributors_with_repository(self, mock_get_contributors):
             ],
         )
         mock_get_contributors.assert_called_once_with(
-            "repo", "2022-01-01", "2022-12-31", ghe, False
+            "repo", "2022-01-01", "2022-12-31", ghe, False, mock_github_connection
         )
 
     @patch("contributors.contributor_stats.ContributorStats")
@@ -153,7 +153,7 @@ def test_get_contributors_skip_users_with_no_commits(self, mock_contributor_stat
         mock_repo.get_commits.side_effect = StopIteration
         ghe = ""
 
-        get_contributors(mock_repo, "2022-01-01", "2022-12-31", ghe, False)
+        get_contributors(mock_repo, "2022-01-01", "2022-12-31", ghe, False, None)
 
         # Note that only user is returned and user2 is not returned here because there were no commits in the date range
         mock_contributor_stats.assert_called_once_with(
@@ -181,7 +181,7 @@ def test_get_contributors_skip_bot(self, mock_contributor_stats):
         mock_repo.get_commits.side_effect = StopIteration
         ghe = ""
 
-        get_contributors(mock_repo, "2022-01-01", "2022-12-31", ghe, False)
+        get_contributors(mock_repo, "2022-01-01", "2022-12-31", ghe, False, None)
 
         # Note that only user is returned and user2 is not returned here because there were no commits in the date range
         mock_contributor_stats.isEmpty()
@@ -202,7 +202,7 @@ def test_get_contributors_no_commit_end_date(self, mock_contributor_stats):
         mock_repo.get_commits.side_effect = StopIteration
         ghe = ""
 
-        get_contributors(mock_repo, "2022-01-01", "", ghe, False)
+        get_contributors(mock_repo, "2022-01-01", "", ghe, False, None)
 
         # Note that only user is returned and user2 is not returned here because there were no commits in the date range
         mock_contributor_stats.assert_called_once_with(
@@ -228,7 +228,7 @@ def test_get_coauthors_from_message_with_noreply_email(self):
 
 Co-authored-by: John Doe <[email protected]>
 """
-        result = get_coauthors_from_message(message)
+        result = get_coauthors_from_message(message, None)
         self.assertEqual(result, ["johndoe"])
 
     def test_get_coauthors_from_message_with_noreply_email_with_id(self):
@@ -239,7 +239,7 @@ def test_get_coauthors_from_message_with_noreply_email_with_id(self):
 
 Co-authored-by: John Doe <[email protected]>
 """
-        result = get_coauthors_from_message(message)
+        result = get_coauthors_from_message(message, None)
         self.assertEqual(result, ["johndoe"])
 
     def test_get_coauthors_from_message_multiple_coauthors(self):
@@ -251,7 +251,7 @@ def test_get_coauthors_from_message_multiple_coauthors(self):
 Co-authored-by: Alice <[email protected]>
 Co-authored-by: Bob <[email protected]>
 """
-        result = get_coauthors_from_message(message)
+        result = get_coauthors_from_message(message, None)
         self.assertEqual(result, ["alice", "bob"])
 
     def test_get_coauthors_from_message_with_regular_email(self):
@@ -262,7 +262,7 @@ def test_get_coauthors_from_message_with_regular_email(self):
 
 Co-authored-by: John Doe <[email protected]>
 """
-        result = get_coauthors_from_message(message)
+        result = get_coauthors_from_message(message, None)
         self.assertEqual(result, ["[email protected]"])
 
     def test_get_coauthors_from_message_case_insensitive(self):
@@ -274,22 +274,22 @@ def test_get_coauthors_from_message_case_insensitive(self):
 co-authored-by: John Doe <[email protected]>
 CO-AUTHORED-BY: Jane Doe <[email protected]>
 """
-        result = get_coauthors_from_message(message)
+        result = get_coauthors_from_message(message, None)
         self.assertEqual(result, ["johndoe", "janedoe"])
 
     def test_get_coauthors_from_message_empty_message(self):
         """
         Test extracting co-authors from an empty commit message.
         """
-        result = get_coauthors_from_message("")
+        result = get_coauthors_from_message("", None)
         self.assertEqual(result, [])
 
     def test_get_coauthors_from_message_no_coauthors(self):
         """
         Test extracting co-authors from a commit message without co-authors.
         """
         message = "Fix bug in login system"
-        result = get_coauthors_from_message(message)
+        result = get_coauthors_from_message(message, None)
         self.assertEqual(result, [])
 
     def test_get_coauthors_from_message_mixed_email_types(self):
@@ -302,7 +302,7 @@ def test_get_coauthors_from_message_mixed_email_types(self):
 Co-authored-by: Bob <[email protected]>
 Co-authored-by: Charlie <[email protected]>
 """
-        result = get_coauthors_from_message(message)
+        result = get_coauthors_from_message(message, None)
         self.assertEqual(result, ["alice", "[email protected]", "charlie"])
 
     def test_get_coauthor_contributors(self):
@@ -327,9 +327,8 @@ def test_get_coauthor_contributors(self):
 
         mock_repo.commits.return_value = [mock_commit1, mock_commit2]
 
-        existing_usernames = set()
         result = get_coauthor_contributors(
-            mock_repo, "2022-01-01", "2022-12-31", "", existing_usernames
+            mock_repo, "2022-01-01", "2022-12-31", "", None
         )
 
         # Alice should have count 2, Bob should have count 1
@@ -345,9 +344,9 @@ def test_get_coauthor_contributors(self):
             elif contributor.username == "bob":
                 self.assertEqual(contributor.contribution_count, 1)
 
-    def test_get_coauthor_contributors_excludes_existing(self):
+    def test_get_coauthor_contributors_includes_all(self):
         """
-        Test that get_coauthor_contributors excludes already existing contributors.
+        Test that get_coauthor_contributors includes all co-authors, even if they are already main contributors.
         """
         mock_repo = MagicMock()
         mock_repo.full_name = "owner/repo"
@@ -361,15 +360,16 @@ def test_get_coauthor_contributors_excludes_existing(self):
 
         mock_repo.commits.return_value = [mock_commit]
 
-        # Alice is already a contributor
-        existing_usernames = {"alice"}
+        # Alice is already a main contributor, but should still be included in co-author results
         result = get_coauthor_contributors(
-            mock_repo, "2022-01-01", "2022-12-31", "", existing_usernames
+            mock_repo, "2022-01-01", "2022-12-31", "", None
         )
 
-        # Only Bob should be in the result
-        self.assertEqual(len(result), 1)
-        self.assertEqual(result[0].username, "bob")
+        # Both Alice and Bob should be in the result
+        self.assertEqual(len(result), 2)
+        usernames = {c.username for c in result}
+        self.assertIn("alice", usernames)
+        self.assertIn("bob", usernames)
 
     @patch("contributors.get_coauthor_contributors")
     def test_get_contributors_with_acknowledge_coauthors(
@@ -397,7 +397,12 @@ def test_get_contributors_with_acknowledge_coauthors(
         mock_get_coauthor_contributors.return_value = [mock_coauthor]
 
         result = get_contributors(
-            mock_repo, "2022-01-01", "2022-12-31", "", acknowledge_coauthors=True
+            mock_repo,
+            "2022-01-01",
+            "2022-12-31",
+            "",
+            acknowledge_coauthors=True,
+            github_connection=None,
         )
 
         # Verify that get_coauthor_contributors was called