chore(codeql): document empty fallback catches

Add explanatory comments to intentional best-effort catches so empty-except fallbacks are auditable.

Author: saagpatel

src/analyzers/activity.py

@@ -138,6 +138,7 @@ def analyze(
                             try:
                                 dates.append(datetime.fromisoformat(pub.replace("Z", "+00:00")))
                             except (ValueError, TypeError):
+                                # Ignore malformed release timestamps when estimating cadence.
                                 pass
                     if len(dates) >= 2:
                         dates.sort()

src/analyzers/cicd.py

@@ -89,6 +89,7 @@ def _has_build_scripts(repo_path: Path) -> bool:
             if "build" in scripts or "test" in scripts:
                 return True
         except (json.JSONDecodeError, OSError):
+            # Malformed or unreadable package metadata means no script signal is detected.
             pass
 
     # Makefile

src/analyzers/dependencies.py

@@ -63,6 +63,7 @@ def cache_inputs_hash(
                     pieces.append(fname.encode())
                     pieces.append(fpath.read_bytes())
                 except OSError:
+                    # Ignore unreadable dependency files in the cache fingerprint.
                     pass
         if not pieces:
             return None
@@ -192,6 +193,7 @@ def _count_dependencies(repo_path: Path, manifests: list[str]) -> int | None:
             dev_deps = len(pkg.get("devDependencies", {}))
             return deps + dev_deps
         except (json.JSONDecodeError, OSError):
+            # Unparseable package metadata falls through to other manifest types.
             pass
 
     if "requirements.txt" in manifests:
@@ -205,6 +207,7 @@ def _count_dependencies(repo_path: Path, manifests: list[str]) -> int | None:
                 and not line.strip().startswith("-")
             )
         except OSError:
+            # Unreadable requirements files fall through to other manifest types.
             pass
 
     if "Cargo.toml" in manifests:
@@ -223,6 +226,7 @@ def _count_dependencies(repo_path: Path, manifests: list[str]) -> int | None:
                     count += 1
             return count
         except OSError:
+            # Unreadable Cargo manifests fall through to other manifest types.
             pass
 
     if "go.mod" in manifests:
@@ -240,6 +244,7 @@ def _count_dependencies(repo_path: Path, manifests: list[str]) -> int | None:
                     count += 1
             return count
         except OSError:
+            # Unreadable Go modules fall through to other manifest types.
             pass
 
     if "pyproject.toml" in manifests:
@@ -258,6 +263,7 @@ def _count_dependencies(repo_path: Path, manifests: list[str]) -> int | None:
                     count += 1
             return count if count > 0 else None
         except OSError:
+            # Unreadable pyproject metadata means no dependency count is available.
             pass
 
     return None

src/analyzers/testing.py

@@ -103,6 +103,7 @@ def _detect_test_framework(repo_path: Path) -> str | None:
             if "cypress" in all_deps:
                 return "cypress"
         except (json.JSONDecodeError, OSError):
+            # Unreadable package metadata simply means no JS test runner was detected.
             pass
 
     # Python — check pyproject.toml for pytest
@@ -115,6 +116,7 @@ def _detect_test_framework(repo_path: Path) -> str | None:
             if "unittest" in content:
                 return "unittest"
         except OSError:
+            # Unreadable project metadata simply means no Python test runner was detected.
             pass
 
     # Python — check for pytest in requirements
@@ -126,6 +128,7 @@ def _detect_test_framework(repo_path: Path) -> str | None:
                 if "pytest" in content:
                     return "pytest"
             except OSError:
+                # Unreadable requirements files are ignored during best-effort detection.
                 pass
 
     # Rust — check Cargo.toml for dev-dependencies
@@ -136,6 +139,7 @@ def _detect_test_framework(repo_path: Path) -> str | None:
             if "[dev-dependencies]" in content:
                 return "cargo-test"
         except OSError:
+            # Unreadable Cargo metadata simply means no Rust test runner was detected.
             pass
 
     # Go — test files convention

src/briefing.py

@@ -388,6 +388,7 @@ def _parse_suggestions_json(raw: str, top_repos: list[dict]) -> list[Suggestion]
                 result.append(Suggestion(name=name, action=action))
             return result
     except (json.JSONDecodeError, IndexError, TypeError):
+        # Fall back to regex extraction when the model response is not valid JSON.
         pass
 
     # Regex fallback: extract quoted strings

src/cli.py

@@ -109,6 +109,7 @@ def _gh_auth_token() -> str | None:
         if result.returncode == 0 and result.stdout.strip():
             return result.stdout.strip()
     except (FileNotFoundError, subprocess.TimeoutExpired):
+        # Missing or slow gh CLI auth falls back to unauthenticated/public mode.
         pass
     return None
 
@@ -3044,6 +3045,7 @@ def _run_list_initiatives_mode(args) -> None:
                 if name:
                     projects_by_name[name.lower()] = proj
         except (OSError, ValueError):
+            # Initiative listing can proceed without portfolio-truth tier context.
             pass
 
     open_initiatives = [i for i in initiatives if i.closed_at is None]
@@ -3076,6 +3078,7 @@ def _run_list_initiatives_mode(args) -> None:
                     days_left = (date.fromisoformat(initiative.deadline) - date.today()).days
                     status_detail = f"at-risk (deadline ≤ {days_left}d)"
                 except ValueError:
+                    # Malformed deadlines keep the generic at-risk label.
                     pass
             elif status == "on-track":
                 status_detail = "on-track"
@@ -3598,6 +3601,7 @@ def _run_main_audit_cycle(args, config_inspection) -> None:
                     resumed_audits.append(_audit_from_dict(audit_dict))
                     resumed_names.add(audit_dict.get("metadata", {}).get("name", ""))
                 except Exception:
+                    # Skip corrupt resume entries and continue with the rest.
                     pass
             if resumed_audits:
                 print_info(f"Resumed {len(resumed_audits)} previously completed repo(s)")
@@ -4968,6 +4972,7 @@ def _fresh_run(repo_path, meta, conn=None):
         try:
             _warehouse_conn.close()
         except Exception:
+            # Warehouse close failures are non-actionable during final cleanup.
             pass
     if _reconcile_diverged:
         sys.exit(1)

src/cloner.py

@@ -52,6 +52,7 @@ def _git_askpass_env(token: str | None) -> Generator[dict[str, str] | None, None
         try:
             script_path.unlink()
         except OSError:
+            # Temporary askpass cleanup is best-effort.
             pass
 
 

src/excel_workbook_helpers.py

@@ -102,6 +102,7 @@ def set_defined_name(wb: Workbook, name: str, attr_text: str) -> None:
     try:
         del wb.defined_names[name]
     except KeyError:
+        # The defined name may not exist yet.
         pass
     wb.defined_names.add(DefinedName(name, attr_text=attr_text))
 

src/issue_creator.py

@@ -27,6 +27,7 @@ def create_audit_issues(
                 skipped.append(repo_name)
                 continue
         except Exception:
+            # If issue listing fails, continue and let create_issue surface any hard error.
             pass
         actions = qw.get("actions", [])
         title = f"[Audit] {repo_name}: {actions[0] if actions else 'Improve audit score'}"

src/libyears.py

@@ -102,6 +102,7 @@ def _parse_pip_deps(path: Path) -> list[tuple[str, str, str]]:
             if match:
                 deps.append((match.group(1), match.group(2), "pypi"))
     except OSError:
+        # Missing or unreadable requirements files have no parseable dependencies.
         pass
     return deps
 
@@ -123,6 +124,7 @@ def _parse_cargo_deps(path: Path) -> list[tuple[str, str, str]]:
                 if match:
                     deps.append((match.group(1), match.group(2), "crates"))
     except OSError:
+        # Missing or unreadable Cargo manifests have no parseable dependencies.
         pass
     return deps
 
@@ -144,6 +146,7 @@ def _parse_pyproject_deps(path: Path) -> list[tuple[str, str, str]]:
                 if match:
                     deps.append((match.group(1), match.group(3), "pypi"))
     except OSError:
+        # Missing or unreadable pyproject files have no parseable dependencies.
         pass
     return deps