fix: populate github_username from noreply emails and config manual_mappings (#44)

bobmatnyc · claude · bobmatnyc · commit d6956e7c8b41 · 2026-04-23T10:39:08.000-04:00
Three gaps caused github_username to be NULL on most developer_identities
rows, so resolve_by_github_username() could not bridge ticketing/PR-review
actors to canonical IDs and ticketing_score was always 0.0:

1. noreply-on-existing-identity: when a noreply email matched an existing
   identity, the early-return branch in resolve_developer() never wrote the
   github_username column. Added _set_github_username_if_missing() and call
   it after both the username_alias and username_identity match branches.
2. bare noreply form: the guard required "+" in the local-part, so
   username@users.noreply.github.com (no numeric prefix) was ignored.
   Extraction now handles both forms.
3. manual_mappings had no github_username field. Added support in
   DeveloperAlias, AliasesManager (load/save/merge/to_manual_mappings),
   and _apply_manual_mappings() (both DB and in-memory paths).

Tests cover all three gaps. No DB migration needed — the column already
exists as nullable.

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/src/gitflow_analytics/config/aliases.py b/src/gitflow_analytics/config/aliases.py
@@ -26,6 +26,7 @@ class DeveloperAlias:
     primary_email: str
     aliases: list[str] = field(default_factory=list)
     name: Optional[str] = None
+    github_username: str | None = None
     confidence: float = 1.0
     reasoning: str = ""
 
@@ -43,6 +44,9 @@ def to_dict(self) -> dict[str, Any]:
         if self.name:
             result["name"] = self.name
 
+        if self.github_username:
+            result["github_username"] = self.github_username
+
         # Only include confidence and reasoning for LLM-generated aliases
         if self.confidence < 1.0:
             result["confidence"] = round(self.confidence, 2)
@@ -122,6 +126,7 @@ def load(self) -> None:
                             primary_email=primary_email,
                             aliases=alias_data.get("aliases", []),
                             name=alias_data.get("name"),
+                            github_username=alias_data.get("github_username"),
                             confidence=alias_data.get("confidence", 1.0),
                             reasoning=alias_data.get("reasoning", ""),
                         )
@@ -278,6 +283,9 @@ def to_manual_mappings(self) -> list[dict[str, Any]]:
             if alias.name:
                 mapping["name"] = alias.name
 
+            if alias.github_username:
+                mapping["github_username"] = alias.github_username
+
             mapping["aliases"] = alias.aliases
 
             # Include confidence and reasoning for LLM-generated mappings
@@ -312,6 +320,7 @@ def merge_from_mappings(self, mappings: list[dict[str, Any]]) -> None:
                 primary_email=primary_email,
                 aliases=mapping.get("aliases", []),
                 name=mapping.get("name"),
+                github_username=mapping.get("github_username"),
                 confidence=mapping.get("confidence", 1.0),
                 reasoning=mapping.get("reasoning", ""),
             )
diff --git a/src/gitflow_analytics/core/identity.py b/src/gitflow_analytics/core/identity.py
@@ -222,6 +222,12 @@ def _apply_manual_mappings(self, manual_mappings: list[dict[str, Any]]) -> None:
                 )
                 aliases = mapping.get("aliases", [])
                 preferred_name = mapping.get("name")  # Optional display name
+                # Bug #44: Allow operators to supply github_username manually
+                # for developers who never commit via the GitHub web UI (so the
+                # noreply heuristic never fires for them).
+                mapping_github_username: str | None = mapping.get("github_username")
+                if mapping_github_username:
+                    mapping_github_username = mapping_github_username.strip().lower() or None
 
                 # Bug #29 fix: canonical_email is required but aliases can be empty
                 # when the mapping only intends to set/rename the primary_name.
@@ -255,6 +261,7 @@ def _apply_manual_mappings(self, manual_mappings: list[dict[str, Any]]) -> None:
                         canonical_id=canonical_id,
                         primary_name=preferred_name or canonical_email.split("@")[0],
                         primary_email=canonical_email,
+                        github_username=mapping_github_username,
                         first_seen=datetime.now(timezone.utc),
                         last_seen=datetime.now(timezone.utc),
                         total_commits=0,
@@ -273,6 +280,12 @@ def _apply_manual_mappings(self, manual_mappings: list[dict[str, Any]]) -> None:
                     )
                     canonical_identity.primary_name = preferred_name
 
+                # Bug #44: Backfill github_username on an already-existing identity
+                # if the manual mapping provides one. This is deferred until after
+                # any merge() so it always applies to the surviving canonical row.
+                if mapping_github_username and not canonical_identity.github_username:
+                    canonical_identity.github_username = mapping_github_username
+
                 # Process each alias
                 for alias_email in aliases:
                     alias_email = alias_email.lower().strip()
@@ -407,11 +420,14 @@ def resolve_developer(
             return canonical_id
 
         # Fix 2: Detect GitHub noreply emails and resolve via username.
-        # Pattern: {numeric_id}+{username}@users.noreply.github.com
+        # Supports both forms:
+        #   - {numeric_id}+{username}@users.noreply.github.com (with ID prefix)
+        #   - {username}@users.noreply.github.com (bare form)
         # Extract the username portion and try to match it against existing aliases.
-        if email.endswith("@users.noreply.github.com") and "+" in email:
+        if email.endswith("@users.noreply.github.com"):
             local_part = email.split("@")[0]
-            github_username = local_part.split("+", 1)[1]  # part after the numeric ID
+            # Handle both forms: "id+username" and bare "username"
+            github_username = local_part.split("+", 1)[1] if "+" in local_part else local_part
             # Look for an existing alias or identity with this username as email/alias
             with self.get_session() as session:
                 # Search aliases where email equals the plain username (common pattern
@@ -426,6 +442,13 @@ def resolve_developer(
                     # Register the noreply address under the same identity so future
                     # lookups hit the cache without another DB round-trip.
                     self._add_alias(username_alias.canonical_id, name, email)
+                    # Bug #44: Backfill github_username on existing identity if missing.
+                    # Without this, identities created from corporate emails before a
+                    # noreply commit ever lands never get their github_username set,
+                    # breaking resolve_by_github_username() for PR review/ticketing.
+                    self._set_github_username_if_missing(
+                        username_alias.canonical_id, github_username
+                    )
                     self._cache[cache_key] = username_alias.canonical_id
                     logger.debug(
                         f"Matched GitHub noreply email {email!r} to username "
@@ -441,6 +464,10 @@ def resolve_developer(
                 )
                 if username_identity:
                     self._add_alias(username_identity.canonical_id, name, email)
+                    # Bug #44: Backfill github_username on existing identity if missing.
+                    self._set_github_username_if_missing(
+                        username_identity.canonical_id, github_username
+                    )
                     self._cache[cache_key] = username_identity.canonical_id
                     logger.debug(
                         f"Matched GitHub noreply email {email!r} to primary identity "
@@ -615,6 +642,51 @@ def _create_identity(self, name: str, email: str, github_username: Optional[str]
 
         return canonical_id
 
+    def _set_github_username_if_missing(self, canonical_id: str, github_username: str) -> None:
+        """Populate ``github_username`` on an existing identity when missing.
+
+        WHY (#44): When we detect a noreply email or a manual mapping for an
+        identity that already exists in the database, the ``github_username``
+        column is often NULL because the identity was created earlier from a
+        corporate email (and ``_create_identity`` only writes the column at
+        creation time). Without this field populated, ``resolve_by_github_username``
+        cannot bridge ticketing/PR-review actors to canonical IDs, which makes
+        the ticketing score always 0.0 for those developers.
+
+        The update only runs when the column is NULL or empty so we never
+        overwrite a previously-resolved username.
+        """
+        if not github_username or not self._database_available:
+            # Keep in-memory cache consistent for the fallback path too.
+            if github_username and not self._database_available:
+                identity = self._in_memory_identities.get(canonical_id)
+                if identity and not identity.get("github_username"):
+                    identity["github_username"] = github_username.lower()
+            return
+
+        username_normalized = github_username.lower().strip()
+        if not username_normalized:
+            return
+
+        with self.get_session() as session:
+            identity = (
+                session.query(DeveloperIdentity)
+                .filter(DeveloperIdentity.canonical_id == canonical_id)
+                .first()
+            )
+            if identity and not identity.github_username:
+                identity.github_username = username_normalized
+                logger.debug(
+                    "Backfilled github_username=%r on canonical_id=%s",
+                    username_normalized,
+                    canonical_id,
+                )
+                # Refresh cache entry for the identity so downstream lookups
+                # see the new value without waiting for a full reload.
+                cached = self._cache.get(canonical_id)
+                if isinstance(cached, dict):
+                    cached["github_username"] = username_normalized
+
     def _add_alias(self, canonical_id: str, name: str, email: str):
         """Add alias for existing developer."""
         with self.get_session() as session:
diff --git a/src/gitflow_analytics/core/identity_stats.py b/src/gitflow_analytics/core/identity_stats.py
@@ -267,6 +267,11 @@ def _apply_manual_mappings_to_memory(self) -> None:
             )
             aliases = mapping.get("aliases", [])
             preferred_name = mapping.get("name")  # Optional display name
+            # Bug #44: Honour github_username from manual mappings so
+            # resolve_by_github_username() works in the in-memory fallback too.
+            mapping_github_username = mapping.get("github_username")
+            if mapping_github_username:
+                mapping_github_username = mapping_github_username.strip().lower() or None
 
             if not canonical_email or not aliases:
                 continue
@@ -276,7 +281,7 @@ def _apply_manual_mappings_to_memory(self) -> None:
             self._in_memory_identities[canonical_id] = {
                 "primary_name": preferred_name or canonical_email.split("@")[0],
                 "primary_email": canonical_email,
-                "github_username": None,
+                "github_username": mapping_github_username,
                 "total_commits": 0,
                 "total_story_points": 0,
             }
diff --git a/tests/core/test_identity.py b/tests/core/test_identity.py
@@ -407,20 +407,25 @@ def test_noreply_email_matches_primary_identity(self, temp_dir):
             "is the extracted username"
         )
 
-    def test_noreply_email_without_plus_creates_new_identity(self, temp_dir):
-        """Noreply-style address without the numeric+username format is treated as a new identity."""
+    def test_noreply_email_bare_form_matches_username_identity(self, temp_dir):
+        """Bug #44 Gap 2: bare ``username@users.noreply.github.com`` resolves to the username identity.
+
+        Prior to the fix, the guard required a ``+`` in the local-part, so the
+        bare form silently fell through to "create new identity". After the fix
+        the bare form is treated the same as the numeric+username form.
+        """
         db_path = temp_dir / "identities.db"
         resolver = DeveloperIdentityResolver(db_path)
 
-        resolver.resolve_developer("Alice", "alice")
+        id_user = resolver.resolve_developer("Alice", "alice")
 
-        # An address that ends with noreply domain but lacks "+" should NOT trigger the
-        # username-extraction path and should therefore create a distinct identity.
+        # Bare noreply form must now match the existing username identity.
         id_plain = resolver.resolve_developer("Alice", "alice@users.noreply.github.com")
-        id_user = resolver.resolve_developer("Alice", "alice")
 
-        # These are separate identities; the noreply path only fires when "+" is present.
-        assert id_plain != id_user
+        assert id_plain == id_user, (
+            "Bare 'username@users.noreply.github.com' should resolve to the same identity "
+            "whose primary_email is the extracted username (Bug #44 Gap 2)."
+        )
 
     def test_noreply_match_is_cached(self, temp_dir):
         """Resolving the same noreply address twice uses the cache on the second call."""
@@ -873,3 +878,104 @@ def test_co_author_counts_not_accumulated(self, temp_dir):
         assert (
             helper["total_commits"] == 1
         ), f"Co-author Helper should have 1 commit, got {helper['total_commits']}"
+
+
+class TestGithubUsernameBackfill:
+    """Bug #44: ensure github_username gets populated on existing identities.
+
+    Without these backfills, resolve_by_github_username() can't bridge ticketing
+    actors to canonical identities, and ticketing_score is always 0.0 for
+    developers whose identity was created before a noreply commit landed.
+    """
+
+    def test_resolve_developer_sets_github_username_on_existing_identity(self, temp_dir):
+        """Bug #44: noreply commit backfills github_username on a pre-existing identity.
+
+        Scenario: identity was created with the corporate email as primary and the
+        GitHub username listed as an alias (typical ``manual_mappings`` output),
+        but ``github_username`` is still NULL because no noreply commit has been
+        seen yet. A later noreply commit must backfill the column on the
+        existing identity so ticketing lookups can bridge to the canonical ID.
+        """
+        db_path = temp_dir / "identities.db"
+
+        # Set up an existing identity with the username as a known alias but
+        # no github_username column populated — mimics the state of every
+        # developer in the production DB before the fix.
+        manual_mappings = [
+            {
+                "primary_email": "alice@company.com",
+                "name": "Alice Smith",
+                "aliases": ["alice-gh"],  # note: no github_username here
+            }
+        ]
+        resolver = DeveloperIdentityResolver(db_path, manual_mappings=manual_mappings)
+
+        canonical_id = resolver.resolve_developer("Alice Smith", "alice@company.com")
+
+        # Sanity: github_username is NOT populated yet.
+        assert (
+            resolver.resolve_by_github_username("alice-gh") is None
+        ), "Pre-condition: no github_username set before the noreply commit lands"
+
+        # Now a noreply commit with the same person's username arrives.
+        resolved = resolver.resolve_developer(
+            "Alice Smith",
+            "12345+alice-gh@users.noreply.github.com",
+        )
+        assert resolved == canonical_id
+
+        # The key assertion: resolve_by_github_username now finds the identity.
+        found = resolver.resolve_by_github_username("alice-gh")
+        assert (
+            found == canonical_id
+        ), "github_username should have been backfilled on the existing identity"
+
+    def test_resolve_developer_bare_noreply_sets_github_username(self, temp_dir):
+        """Bug #44 Gap 2: bare username@users.noreply.github.com form is supported."""
+        db_path = temp_dir / "identities.db"
+        resolver = DeveloperIdentityResolver(db_path)
+
+        # Pre-create an identity whose primary_email is the bare username,
+        # so the noreply path's "username_identity" branch fires.
+        canonical_id = resolver.resolve_developer("Octocat", "octocat")
+
+        # Bare noreply form (no numeric ID prefix).
+        resolved = resolver.resolve_developer(
+            "Octocat",
+            "octocat@users.noreply.github.com",
+        )
+        assert resolved == canonical_id
+
+        # github_username must be populated so ticketing lookups succeed.
+        found = resolver.resolve_by_github_username("octocat")
+        assert found == canonical_id, (
+            "Bare 'username@users.noreply.github.com' form must backfill github_username "
+            "so resolve_by_github_username() can bridge ticketing actors."
+        )
+
+    def test_manual_mapping_populates_github_username(self, temp_dir):
+        """Bug #44 Gap 3: manual_mappings can supply github_username for existing identities."""
+        db_path = temp_dir / "identities.db"
+
+        # Step 1: create an identity via a commit (no github_username).
+        resolver_first = DeveloperIdentityResolver(db_path)
+        canonical_id = resolver_first.resolve_developer("Bob Builder", "bob@company.com")
+        assert resolver_first.resolve_by_github_username("bob-builder") is None
+
+        # Step 2: reload with a manual mapping that supplies github_username.
+        manual_mappings = [
+            {
+                "primary_email": "bob@company.com",
+                "name": "Bob Builder",
+                "github_username": "bob-builder",
+                "aliases": [],
+            }
+        ]
+        resolver = DeveloperIdentityResolver(db_path, manual_mappings=manual_mappings)
+
+        found = resolver.resolve_by_github_username("bob-builder")
+        assert found == canonical_id, (
+            "Manual mapping with github_username must backfill the field on an "
+            "already-existing identity so ticketing bridges to the canonical ID."
+        )
