feat(seo-data): C3 — internal link graph; orphans + click depth, measured · fe41986be9 - claude_mac

feat(seo-data): C3 — internal link graph; orphans + click depth, measured

seo-analyzer.md:613 asks "Every important page reachable within 3 clicks?"
and :616 asks "Orphan pages (no inbound internal links)?". Neither ever had a
command — same shape as the sameAs check before W3. This is that command.

My earlier reservation ("costs a lot of network") was wrong and the
measurement killed it: 24 pages in 2.7s, 86 in 3.8s. Cheap enough to always
run on FULL.

EXHAUSTIVE OR NOTHING is the design constraint, not a nicety. Orphans cannot
be sampled: proving a page has no inbound link means having read every other
page. So when the crawl is capped or any page fails, orphans are WITHHELD —
`orphans_withheld: true` and no list. A false orphan ("page X has no inbound
links" when it does) sends a client fixing what is not broken; that is the
worst finding this tool could emit. The cap does not degrade the result, it
invalidates it.

SPA refusal: on a client-rendered site the links are not in the HTML and
every page reads as orphaned. That is catastrophic, so an empty graph returns
degraded/no_links_in_html instead of a full false-positive list. No JS
rendering by design — that is the R1/R2 arbitration, not something to smuggle
in here.

Verified against BOTH live sites and against a planted failure, because two
clean results are not evidence a detector detects:
- native PHP: 24 pages, 335 links, depth 2, 0 orphans
- Astro: 86 pages, 2015 links, depth 2, 0 orphans
- fixture with a planted orphan + a 4-click chain: both found. Filters proven
  on real shapes seen live — /css/main.css?v=1778157313, #anchors, mailto:,
  tel:, external hosts, .png. /b/ in markup vs /b in sitemap unify to one node
  rather than a phantom orphan pair.

Fixed a flaw in my own mock while writing that test: a single page.html
fixture cannot express a GRAPH (every node gets identical links), so the mock
is now pages.json = {url: html}.

Verified: seo-data 122 -> 136 pass, 0 fail; full suite green; shellcheck +
py_compile clean.

This commit is contained in:

Bastien Chanot

2026-07-17 12:32:42 +02:00

parent dca977bb27

commit fe41986be9

7 changed files with 271 additions and 1 deletions

									
										lib/seo-data/fixtures-linkgraph/sitemap.xml
									
		+10
		
												View File
												
				@@ -0,0 +1,10 @@

				<?xml version="1.0" encoding="UTF-8"?>

				<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">

				  <url><loc>https://ex.com/</loc></url>

				  <url><loc>https://ex.com/a</loc></url>

				  <url><loc>https://ex.com/b</loc></url>

				  <url><loc>https://ex.com/deep</loc></url>

				  <url><loc>https://ex.com/deeper</loc></url>

				  <url><loc>https://ex.com/deepest</loc></url>

				  <url><loc>https://ex.com/orphan</loc></url>

				</urlset>