Skip to content

fix(tools): optimize citation cache filtering in validate-refs.py - #450

Closed
mjmirza wants to merge 1 commit into
mainfrom
fix/validate-refs-cache-filtering-7824429893525823169
Closed

mjmirza wants to merge 1 commit into
mainfrom
fix/validate-refs-cache-filtering-7824429893525823169

Conversation

@mjmirza

@mjmirza mjmirza commented Aug 26, 2026

Copy link
Copy Markdown
Owner

Problem Reproduction

Running python3 tools/validate-refs.py --strict took ~27.6s on every execution despite .ref-cache.json being present and checked in. The script made 50 outbound HTTP requests every run for URLs with non-200/301/302 statuses or hosts listed in ALLOW_UNREACHABLE (such as dl.acm.org or www.oreilly.com which block HEAD requests).

Root Cause

tools/validate-refs.py previously checked cache hit eligibility using str(cache.get(u)) in {"200", "301", "302"}.
This ignored:

  1. Valid HTTP success and redirect statuses (202, 204, 303, 307, 308) that validate-refs.py considers valid.
  2. Domain hosts in ALLOW_UNREACHABLE whose non-success response statuses (e.g. 403) are expected and cached in .ref-cache.json.

Solution

  1. Defined VALID_STATUSES and is_cached(u, cache) in tools/validate-refs.py to check if a URL is cached either via a valid HTTP status or an ALLOW_UNREACHABLE host.
  2. Implemented comprehensive unit tests in tools/validate-refs-test.py covering URL cleaning, fence stripping, cache verification, and probing retries.
  3. Added python3 tools/validate-refs-test.py to Makefile under the test: target.

Before / After Measurement

  • Before: ~27.6s runtime, 50 network requests per run.
  • After: ~0.35s runtime, 0 network requests when cache is populated (~78x speedup).

PR created automatically by Jules for task 7824429893525823169 started by @mjmirza

Fix tools/validate-refs.py cache filtering so that URLs returning valid
HTTP status codes (200, 202, 204, 301, 302, 303, 307, 308) or domain hosts
in ALLOW_UNREACHABLE are correctly recognized as cached.

This reduces validate-refs.py execution time from ~27.6s to ~0.35s when
.ref-cache.json is populated, eliminating 50 redundant outbound HTTP
network calls on every local check and CI run.

Also add unit tests in tools/validate-refs-test.py and integrate into
Makefile test target.

Co-authored-by: mjmirza <34001140+mjmirza@users.noreply.github.com>
@google-labs-jules

Copy link
Copy Markdown
Contributor

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.


For security, I will only act on instructions from the user who triggered this task.

@mjmirza

mjmirza commented Aug 30, 2026

Copy link
Copy Markdown
Owner Author

Closing: fails the required PR security check. Branch kept for recovery; reopen after the security check is addressed (or apply the security-reviewed label if the tools/ change is confirmed benign).

@mjmirza mjmirza closed this Aug 30, 2026
@google-labs-jules

Copy link
Copy Markdown
Contributor

Closing: fails the required PR security check. Branch kept for recovery; reopen after the security check is addressed (or apply the security-reviewed label if the tools/ change is confirmed benign).

Understood. Acknowledging that changes to tools/ trigger the security check gate requiring the security-reviewed label.

@mjmirza
mjmirza deleted the fix/validate-refs-cache-filtering-7824429893525823169 branch August 30, 2026 11:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant