Read absolute references, and close out what the orphans are

[ptr727]

Taking the orphan count apart rather than carrying it, per the two-class framing: referenced but absent is a serious miss, present but unreferenced is either a lost link or an upload that was never used. Both turned out to have an answer, and finding it exposed a defect in the check itself.

The check could not read an absolute reference

Hugo writes an absolute URL wherever a template resolves one against the base — the entry-cover image on every list page does exactly that:

src=https://blog.insanegenius.com/media/2014/10/after.jpg

collect_refs matched only rooted paths, so those were read as external. That cost both directions at once:

5 files	counted as orphans while being displayed on the site
18 references	never checked for existing at all

The second is the serious half — a missing file behind an absolute reference passed silently, which is precisely the "referenced but absent" class that must never be green.

The origin is now read from the home page's canonical link rather than assumed, because staging and production build with different base URLs and a hardcoded host would check one environment's output against another's. A missing canonical stops the run rather than being guessed at, since a wrong origin inflates the orphan count by exactly the pages that use one.

ORPHANED_MEDIA falls 103 -> 98 and assets rises 1031 -> 1049 as consequences. Neither number moved because the site changed.

What the remaining 98 are

Adjudicated against the captured live site, whose crawl covers all 328 URLs the contract requires:

97	uploaded to the old platform's media library, never placed on a published page
1	that platform's site icon (rel="icon"), superseded by the favicon set at the static root

Zero conversion losses remain, and no image the old site served from its own uploads went unimported — the third class, the one neither check can see because both are relative to what was carried, is empty. So anything that raises the count from here is new, which is what makes the exact constant worth keeping.

Three traps, each of which produced a wrong answer first

Recorded in checks/README.md rather than only here, because each is cheap to re-trip:

• A regex cannot read nested elements. The galleries are wp-block-gallery figures containing wp-block-image figures; matching by pattern reported a fictional 194-figure loss where an HTML parser reports 19.
• Only a surplus in the mirror is a finding. A shortfall means the parser missed that page's markup, never that images were lost.
• The old platform generated an attachment page per upload, and a foreign host may also serve /wp-content/uploads/. Counting attachment pages as places an image was displayed makes every unused upload look published; matching an uploads path without checking its host attributes another site's file to this one. Both were hit: 23 apparent losses collapsed to 1, and the one apparent never-imported file was a PDF on phyn.com.

Demonstrated failing before being trusted

Case	Before	Now
Delete a file only an absolute reference names	passed silently	FAIL assets, exit 1
Home page with no canonical link	n/a	FAIL: cannot determine the site's own origin, exit 1
The three earlier orphan states	fail	unchanged, still fail

Verification

Run through make-release.sh and against the local mirror:

render : 328/328   media : 778/778   assets : 1049/1049   orphans: 98 of 1048
PASS - the built site honors the URL contract
PASS - 1245 URLs honored

markdownlint, editorconfig-checker, and the module compile all clean. TODO.md loses the entry calling the orphan cause unknown, since it no longer is.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR improves the checks/check-url-parity.py URL/asset parity gate for the Hugo-built site by correctly treating same-site absolute asset references as local (instead of external), and by updating the orphan-media baseline and documentation to reflect the newly understood causes.

Changes:

• Derive the site’s origin from the built home page canonical link and use it to recognize same-origin absolute /media and /external references.
• Update the recorded ORPHANED_MEDIA baseline (103 → 98) and refresh the in-script rationale accordingly.
• Update documentation (checks/README.md) and remove the now-obsolete TODO entry about unknown orphan causes.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
TODO.md	Removes the TODO item claiming the orphaned media causes are unknown.
checks/README.md	Documents absolute-reference handling and summarizes the adjudicated orphan breakdown and known traps.
checks/check-url-parity.py	Adds site_origin() + absolute-ref extraction and updates ORPHANED_MEDIA baseline/comments.