Fix contributor heatmap dropdown issue and restore original descriptions

- Add detailed logging to repo_dropdown and directory_dropdown to debug issue
- Remove top-level docstrings from all three heatmap files
- Restore original long-form PopoverBody descriptions for contributor/reviewer heatmaps
- Restore original short-form description for contribution heatmap
- Add back NOTE comment explaining query logic in repo_files_query.py

Author: EngCaioFonseca

8Knot/pages/codebase/visualizations/cntrb_file_heatmap.py

@@ -1,9 +1,3 @@
-"""
-Contributor File Heatmap Visualization
-
-Shows when contributors who touched files were last active in the repository.
-"""
-
 from dash import html, dcc, callback
 import dash_bootstrap_components as dbc
 import dash_mantine_components as dmc
@@ -34,12 +28,13 @@
                 dbc.PopoverHeader("Graph Info:"),
                 dbc.PopoverBody(
                     """
-                    This visualization analyzes when contributors to each file/directory
-                    were last active in the repository. A contributor is someone who has
-                    opened at least one pull request touching a file. The heatmap shows
-                    the count of contributors whose last activity falls in each month.
-                    This helps identify files where past contributors may no longer be
-                    actively maintaining the code.
+                    This visualization analyzes the activity of the contributors to sub-sections (files or folders)
+                    of a repository. Specifically, this heatmap identifies the last time a sub-section's contributors
+                    (those people who have opened at least one pull request to a sub-section) last contributed to the
+                    repository. See the definition of "contribution" on the Info page for more information. This could be
+                    interpreted as monitoring technical knowledge retention of codebase components: if a sub-section's
+                    past contributors are no longer active in the repository, maintainership of that sub-section could
+                    be insufficient and require attention.
                     """
                 ),
             ],
@@ -140,8 +135,10 @@ def toggle_popover(n, is_open):
 )
 def repo_dropdown(repo_ids):
     """Populate repository dropdown."""
-    logging.debug(f"{VIZ_ID} - repo_dropdown called with {len(repo_ids) if repo_ids else 0} repos")
-    return hu.build_repo_dropdown_data(repo_ids, rfq)
+    logging.warning(f"{VIZ_ID} - repo_dropdown called with repo_ids={repo_ids}")
+    result = hu.build_repo_dropdown_data(repo_ids, rfq)
+    logging.warning(f"{VIZ_ID} - repo_dropdown returning: {result}")
+    return result
 
 
 @callback(
@@ -154,8 +151,9 @@ def repo_dropdown(repo_ids):
 )
 def directory_dropdown(repo_id):
     """Populate directory dropdown based on selected repository."""
-    logging.debug(f"{VIZ_ID} - Loading directories for repo_id={repo_id}")
+    logging.warning(f"{VIZ_ID} - directory_dropdown called with repo_id={repo_id}")
     if repo_id is None:
+        logging.warning(f"{VIZ_ID} - directory_dropdown repo_id is None, returning TOP_LEVEL_DIRECTORY")
         return [hu.TOP_LEVEL_DIRECTORY], hu.TOP_LEVEL_DIRECTORY
 
     # Wait for cache with timeout
@@ -174,7 +172,9 @@ def directory_dropdown(repo_id):
     df = hu.prepare_file_df(df)
     directories = hu.get_directories(df)
 
-    logging.debug(f"{VIZ_ID} - Found {len(directories)} directories")
+    logging.warning(
+        f"{VIZ_ID} - directory_dropdown returning {len(directories)} directories, default={hu.TOP_LEVEL_DIRECTORY}"
+    )
     return directories, hu.TOP_LEVEL_DIRECTORY
 
 

8Knot/pages/codebase/visualizations/contribution_file_heatmap.py

@@ -1,9 +1,3 @@
-"""
-Contribution File Heatmap Visualization
-
-Shows PR activity (opened/merged) per file/directory over time.
-"""
-
 from dash import html, dcc, callback
 import dash_bootstrap_components as dbc
 import dash_mantine_components as dmc
@@ -32,9 +26,8 @@
                 dbc.PopoverHeader("Graph Info:"),
                 dbc.PopoverBody(
                     """
-                    This visualization analyzes the activity of pull requests to sub-sections
-                    (files or folders) of a repository over time. The heatmap shows the number
-                    of PRs opened or merged for each file/directory by month.
+                    This visualization analyzes the activity of the open or merged pull requests to sub-sections
+                    (files or folders) of a repository.
                     """
                 ),
             ],

8Knot/pages/codebase/visualizations/reviewer_file_heatmap.py

@@ -1,9 +1,3 @@
-"""
-Reviewer File Heatmap Visualization
-
-Shows when reviewers of file PRs were last active in the repository.
-"""
-
 from dash import html, dcc, callback
 import dash_bootstrap_components as dbc
 import dash_mantine_components as dmc
@@ -34,12 +28,13 @@
                 dbc.PopoverHeader("Graph Info:"),
                 dbc.PopoverBody(
                     """
-                    This visualization analyzes when reviewers of each file/directory
-                    were last active in the repository. A reviewer is someone who has
-                    reviewed at least one pull request touching a file. The heatmap shows
-                    the count of reviewers whose last activity falls in each month.
-                    This helps identify files where past reviewers may no longer be
-                    actively maintaining the code.
+                    This visualization analyzes the activity of the reviewers to sub-sections (files or folders)
+                    of a repository. Specifically, this heatmap identifies the last time a sub-section's reviewer
+                    (those people who have reviewed at least one pull request to a sub-section) last contributed to the
+                    repository. See the definition of "contribution" on the Info page for more information. This could be
+                    interpreted as monitoring technical knowledge retention of codebase components: if a sub-section's
+                    past reviewers are no longer active in the repository, maintainership of that sub-section could
+                    be insufficient and require attention.
                     """
                 ),
             ],

8Knot/queries/repo_files_query.py

@@ -34,6 +34,12 @@ def repo_files_query(self, repos):
     if len(repos) == 0:
         return None
 
+    # NOTE: in below query, for each repo_id we're interested in,
+    # we pre-compute the most recent augur analysis date. This allows
+    # us to quickly get the names of the files in the repo that
+    # exist most-currently, dropping files that have been added and
+    # then deleted in the past.
+
     # Use pre-computed materialized view for faster performance
     query_string = """
                     SELECT