feat(blog): link integrity - audit, redirects, multilingual rewrite, CI guards

[miquelmatoses]

Summary

Phase 17.10. Three layers so internal blog links never break silently.

Layer A - one-shot audit (scripts/audit_blog_links.py)

Reads every published article from the API, extracts links from each language body, classifies internal/external, validates internal targets against the live slug set, probes externals (broken vs flaky, no false positives for 403/429/5xx/timeout), and proposes redirects via slug/title similarity. Report at docs/seo/links-audit-20260528.md.

Findings: 6 dead internal slugs across 60 link instances (5 left doubled by an old rename script e.g. ...-more-honest-data-more-honest-data, 1 genuine rename), 100 external 404s (mostly stale DOIs), 0 multilingual mismatches.

Markdown parsing handles balanced parens so DOIs like 10.1016/S0092-6566(03)00046-1 are not truncated into false 404s.

Layer C - automatic resilience

• db/migrations/016_blog_slug_redirects.sql: blog_slug_redirects(slug_old PK -> slug_new, created_at, reason), idempotent, seeded with the 6 audited redirects + the known big-five-vs-disc-vs-belbin case (currently dormant — that slug still resolves to a live article; the spec's "no longer exists" premise is outdated, documented in the row comment).
• GET /blog/<slug> returns 308 to /blog/<slug_new> for a dead slug with a redirect. Single hop; target must be a live post, so chains and A->B->A cycles never loop or land on a 404. Degrades to 404 if the table is unmigrated, so the code deploy is safe before the SQL is applied.
• BlogArticlePage rewrites internal links to the active locale only when the target has that locale (else English fallback), using a new languages[] field on the /blog list endpoint carried in window.__BLOG_ARTICLES__. Replaces the previous blind prefix that mislabeled every link /<lang>/blog/....

Layer B - permanent guards

• api/tests/test_internal_links_integrity.py: scans prerendered dist, fails if any internal /blog link resolves to neither a live article nor a redirect. Verified non-vacuous (catches all 6 without the seed).
• api/jobs/external_links_check.py + cron + DDL 07: weekly probe into cercol_seo.external_links_status, emails a digest of links newly broken since last week (LINKS_ALERT_EMAIL).

All markdown link parsing lives in one place (api/blog_links.py), shared by the audit, the cron job, and the CI guard.

Test plan

• pytest api/ - 192 passed (incl. 6 redirect, 2 external-job, 1 integrity)
• integrity test passes against full build:full dist; proven to fail without the redirect seed
• vitest run - 211 passed (incl. 7 localizeBlogLinks)
• CI frontend job: build:full + integrity guard against complete dist
• Post-merge: apply migration 016 via SSH; curl api.cercol.team/blog/big-five-vs-disc-vs-belbin (dormant -> 200; a truly dead slug -> 308)

Deploy notes

No migration runner in this repo: migration 016 is applied manually via sudo -u postgres psql cercol -f db/migrations/016_blog_slug_redirects.sql after the backend deploy (runbook updated). The new cron and BigQuery DDL 07 are installed per the runbook (not auto-installed).

Known follow-up (content debt, not in scope)

The 60 broken links are resolved by redirects but still live in the published article bodies. Fixing the source content (and the dead external DOIs) is tracked separately.

🤖 Generated with Claude Code