build: migrate type checker from mypy to basedpyright

[vringar]

Summary

Migrates OpenWPM's static type checker from mypy to basedpyright and resolves the genuine type errors that surfaced in the process. Organised as three commits.

1. feat(typing): overload query_db and get_javascript_entries

db_utils.query_db (and the wrapper get_javascript_entries) returns list[sqlite3.Row] by default and list[tuple[Any, ...]] only with as_tuple=True. The old union return type forced every default-mode caller to add assert isinstance(row, sqlite3.Row) or # type: ignore. @overload signatures now make the return type follow the as_tuple keyword:

call	static return type
query_db(db, q)	list[sqlite3.Row]
query_db(db, q, as_tuple=False)	list[sqlite3.Row]
query_db(db, q, as_tuple=True)	list[tuple[Any, ...]]
query_db(db, q, as_tuple=some_bool)	list[sqlite3.Row] | list[tuple[Any, ...]]

as_tuple is now keyword-only — the overloads would otherwise overlap. Redundant isinstance assertions in the test suite are removed.

2. build: migrate type checker from mypy to basedpyright

• mypy replaced with basedpyright in pyproject.toml, .pre-commit-config.yaml, and the conda environment files
• typeCheckingMode = "recommended"
• a multiprocess type stub added so the untyped library stops producing false positives

3. fix(typing): resolve type errors surfaced by basedpyright

Genuine bugs and type errors basedpyright caught:

• a possibly-unbound browser_profile_path in BrowserManager
• missing None-checks before open() / screenshot paths
• an exception passed where traceback.format_exc() expected a frame limit
• an incompatible store_blob override in the in-memory storage provider, realigned to the abstract signature
• precise Queue payload types on the BrowserManager / StorageController IPC queues
• the storage base classes marked explicitly ABC

Also deletes the unmaintained build_cookie_table utility and the cookie module it was the sole importer of — both depended on the long-uninstallable netlib package and were already un-importable.

The remaining recommended-mode findings (untyped third-party libraries, intentional bad-input tests, the manual_test.py debug script) are frozen in .basedpyright/baseline.json, so CI gates only on newly introduced issues.

Test plan

• basedpyright — 0 errors, 0 warnings
• pre-commit run --all-files passes
• full pytest suite — 137 passed, 3 skipped. The lone failure, test_audio_fingerprinting, is the known pre-existing flake (@pytest.mark.skipif(CI), "Flaky on CI") and is unrelated to these changes.
• CI

[Copilot]

Pull request overview

This PR improves static typing for openwpm.utilities.db_utils.query_db and its wrapper get_javascript_entries by using @overload so the return type is determined by the as_tuple argument (rows by default, tuples only when as_tuple=True), without changing runtime behavior.

Changes:

• Add @overload signatures for query_db to precisely type as_tuple=False vs as_tuple=True.
• Apply the same overload pattern to get_javascript_entries.
• Update typing imports to support overload/Literal.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 68.00000% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.12%. Comparing base (06d755a) to head (78fdbe4).

Files with missing lines	Patch %	Lines
openwpm/commands/utils/XPathUtil.py	0.00%	8 Missing ⚠️
test/test_mp_logger.py	0.00%	2 Missing ⚠️
test/test_profile.py	0.00%	2 Missing ⚠️
openwpm/browser_manager.py	75.00%	1 Missing ⚠️
openwpm/config.py	83.33%	1 Missing ⚠️
openwpm/js_instrumentation.py	0.00%	1 Missing ⚠️
openwpm/socket_interface.py	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1170      +/-   ##
==========================================
+ Coverage   62.19%   68.12%   +5.92%     
==========================================
  Files          40       38       -2     
  Lines        3902     3576     -326     
==========================================
+ Hits         2427     2436       +9     
+ Misses       1475     1140     -335     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

openwpm/utilities/db_utils.py:68

• Same overload ambiguity as query_db: as_tuple: Literal[True] = ... makes the True overload appear callable without specifying as_tuple, overlapping with the default-False overload. Prefer making as_tuple=True required in this overload (no default) so inference can’t accidentally select the tuple-returning overload for default calls.

@overload
def get_javascript_entries(
    db: Path, all_columns: bool = ..., as_tuple: Literal[True] = ...
) -> List[Tuple[Any, ...]]: ...