Spring cleanup: bootstrap NaN-gating, mypy fixes, doc snippet hardening

[igerber]

Summary

• Migrate imputation_bootstrap.py and two_stage_bootstrap.py to shared compute_effect_bootstrap_stats() from bootstrap_utils.py, gaining NaN filtering, SE<=0 guards, and warning messages that were previously missing
• Add @overload to solve_ols/_solve_ols_numpy to resolve all 15 mypy tuple-unpacking errors without touching call sites; add assert X is not None guards for Optional indexing across 10 files (81→9 mypy errors, remaining 9 are mixin method attr-defined)
• Replace blanket except NameError: pass in test_doc_snippets.py with explicit allow-list of 12 context-dependent snippets — unexpected NameErrors now fail the test
• Update TODO.md: remove resolved bootstrap NaN-gating item, mark doc snippet issue resolved, replace stale "282 pyright errors" with current mypy status

Methodology references (required if estimator / math changes)

• Method name(s): Multiplier bootstrap inference (Imputation DiD, Two-Stage DiD)
• Paper / source link(s): Borusyak, Jaravel & Spiess (2024); Gardner (2022)
• Any intentional deviations from the source (and why): None — migrated to existing shared utility that already implements the correct methodology

Validation

• Tests added/updated: tests/test_doc_snippets.py (allow-list replaces blanket catch)
• Full test suite: 1808 passed, 67 skipped, 0 failures
• mypy: 81→9 errors (all remaining are mixin method attr-defined)
• Backtest: N/A — no behavioral change to bootstrap inference (shared utility computes identical results when inputs are finite)

Security / privacy

• Confirm no secrets/PII in this PR: Yes

---

Generated with Claude Code

[github-actions]

Overall Assessment

Looks good. I did not find any unmitigated P0/P1 issues in the diff-scoped estimator/bootstrap changes; the highest finding is P2 in the new doc-snippet test harness.

Executive Summary

• The only behavior-affecting methodology changes are the ImputationDiD and TwoStageDiD multiplier bootstrap paths.
• Cross-checking those paths against the Methodology Registry found no undocumented deviation: both estimators already document multiplier bootstrap as a library extension, and the shared helper enforces the project’s intended NaN/zero-SE gating consistently across SE, CI, and p-value [docs/methodology/REGISTRY.md:828] [docs/methodology/REGISTRY.md:893] [docs/methodology/REGISTRY.md:899] [diff_diff/bootstrap_utils.py:206].
• The bootstrap NaN-gating migration is applied consistently to overall, event-study, and group outputs in both estimators [diff_diff/imputation_bootstrap.py:241] [diff_diff/two_stage_bootstrap.py:239].
• The new doc-snippet NameError allow-list is keyed by unstable positional block IDs, so a future docs edit can silently whitelist the wrong snippet instead of failing on an unexpected NameError [tests/test_doc_snippets.py:69] [tests/test_doc_snippets.py:131] [tests/test_doc_snippets.py:354].
• The refreshed large-file counts in TODO.md are already stale for several files, so that housekeeping table is not reliable as written [TODO.md:24].
• I could not run pytest here because the environment does not have pytest installed, but an in-memory compile() check of all touched Python files succeeded.

Methodology

• Severity: None. Impact: No diff-scoped methodology defect identified. The affected methods are ImputationDiD multiplier bootstrap and TwoStageDiD GMM-influence multiplier bootstrap; the registry already documents both the multiplier-bootstrap extension and NaN invalid-inference behavior, and the new call sites delegate to the shared helper consistently for overall, event-study, and group outputs [docs/methodology/REGISTRY.md:828] [docs/methodology/REGISTRY.md:893] [docs/methodology/REGISTRY.md:899] [diff_diff/bootstrap_utils.py:206] [diff_diff/imputation_bootstrap.py:241] [diff_diff/two_stage_bootstrap.py:239]. Concrete fix: None.

Code Quality

• Severity: None. Impact: I did not find a diff-scoped runtime regression in the mypy/typing cleanup or the assertion insertions. Concrete fix: None.

Performance

• Severity: None. Impact: No diff-scoped performance regression identified. The estimator refactor removes duplicated local bootstrap-stat logic and keeps using the same shared batched weight-generation path. Concrete fix: None.

Maintainability

• Severity: None. Impact: No maintainability blocker identified in the estimator changes themselves. Concrete fix: None.

Tech Debt

• Severity: P3. Impact: The refreshed "Large Module Files" table is already inaccurate in the checked-in tree; for example, it lists visualization.py and linalg.py at 1727 lines, but the current files are 1764 and 1829 lines. That makes the new housekeeping data unreliable immediately on merge [TODO.md:24] [diff_diff/visualization.py] [diff_diff/linalg.py]. Concrete fix: regenerate the table from the current tree, ideally via script, before merge instead of hand-editing counts.

Security

• Severity: None. Impact: No diff-scoped secret-handling, trust-boundary, or code-injection issue identified. Concrete fix: None.

Documentation/Tests

• Severity: P2. Impact: The new _CONTEXT_DEPENDENT_SNIPPETS allow-list is keyed by positional block{idx} IDs, and those IDs depend on extraction/index order rather than stable snippet identity. Because _extract_snippets() numbers all directive blocks first and shorthand :: blocks second, inserting or converting an earlier snippet can silently move a stale exemption onto a different snippet, weakening the NameError hardening this PR is trying to add [tests/test_doc_snippets.py:69] [tests/test_doc_snippets.py:131] [tests/test_doc_snippets.py:354]. Concrete fix: key exemptions by stable file-relative identity, such as relpath + normalized snippet hash or an explicit inline marker/comment, not by block{idx}.
• Severity: None. Impact: Relevant regression coverage already exists around the shared helper and both estimator bootstrap paths [tests/test_bootstrap_utils.py:14] [tests/test_imputation.py:897] [tests/test_two_stage.py:999], but I could not execute pytest in this environment because pytest is not installed. Concrete fix: None.