The problem it fixes
Multi-page sites version their CSS and JS with ?v=N cache busters. Bump passes tend to be page-local: the page you edited gets ?v=48, the other 83 pages keep ?v=33. Every stale page then loads the current asset file - but returning browsers hold their cached copy under the old key, so the deployed code never actually runs there. No error, no warning. This scanner was extracted from a production site where 84 pages had drifted over three months of page-local bumps.
What it does
- scans a file tree - every
<script src>and<link href>ref to a local.jsor.cssasset, across HTML and PHP files - groups refs per asset and flags any asset referenced under more than one version key
- catches bare refs too - a versionless ref mixed with keyed refs is drift
- CI-friendly - exit 1 when drift is found, exit 0 when clean, so it gates a pipeline
- JSON mode -
--jsonemits a structured report for tooling
Usage
One file, no dependencies, no network:
php audit.php /var/www/site- scan a directory treephp audit.php . --exclude=fixt,backups- skip directoriesphp audit.php . --json- machine-readable report
Frequently asked questions
What does stale-asset-audit do?
one PHP file that finds pages serving a cached asset under an old ?v= cache key; zero dependencies, CI-friendly exit codes
Where is the code?
The repository is at https://github.com/bryanhamiltondev/stale-asset-audit - production-extracted, MIT-licensed where noted in the repo.
Need someone who ships like this?
Bryan Hamilton is a full-stack web engineer with 25+ years in PHP and JavaScript, available immediately for remote, hybrid or on-site roles in the NYC metro area.