SEO checks: one file per check, so PRs adding checks stop conflicting

LU
2d ago
+1413-1147

PRs that add an SEO check kept conflicting with each other: each took the next free number and appended to the same four places in check_seo_html.py and its test file. #1093 and #1207 both claim check 14 on main, and here on rebrand-doors the newsletter check ran twice, once as "12" (colliding with the resource-subsets check) and once as "19".

Now each check is its own module, scripts/seo_checks/<name>.py: a docstring (its first line is the summary title) and a check(site) function. Its tests go in scripts/tests/test_seo_<name>.py. The runner loads every module in that folder in name order, so adding a check means adding two files and editing nothing shared. The numbers are gone. The CLI, exit code and report-only output are unchanged, so deploy.yaml, rebrand-preview.yaml and rehearse_launch.py need no change.

The runner refuses to start if the folder is empty or a module lacks a docstring or check, and a runner test confirms every module file is loaded, so a check can't silently drop out.

Audit of checks and tests

  • Removed: the duplicate newsletter run.
  • Tests replaced: the runner test that built a fake whole site (homepage, a cluster page, FLoRA, the glossary hub) just so main() returned 0. Every new check that needs a page had to edit it. It is now covered by stub checks. The breadcrumb-links test now runs the check, not just the parser.
  • Kept: the other tests. Each one exercises a pass or fail case of a real regression, and I found no padding worth deleting.
  • Overlaps checked, all kept:
    • homepage_assets catches the highlight.js stylesheet, which conditional_assets doesn't look at.
    • search_heading catches the search overlay's <h1> (on every page via baseof.html) on pages with no heading of their own, where single_h1 can't.
    • homepage_share_image requires 1200×630 and summary_large_image, which share_image_metadata doesn't.
  • Dropped: the FLoRA citation check. It looked for one hard-coded DOI on one page, which guards content rather than a template.

Verification

  • Built rebrand-doors with Hugo. Old and new runners give the same result (all pass, exit 0), and the report-only output is identical.
  • Injected one fault for each of the 24 original checks into a copy of the build. Old and new code flag exactly the same items for every check, and both exit 1.
  • python3 -m unittest discover -s scripts/tests passes, including 41 SEO tests (41 before, minus the fake-site test and the two FLoRA tests, plus 3 runner tests).

Checks still to move when main merges in

main has checks in the old numbered layout: the card alt-text check, and the open PRs #1093 (Bulgarian glossary) and #1207 (native Google Forms). main's FLoRA citation check (11) should be dropped, not moved. When the others reach this branch, move each into its own module: take the check_* function into scripts/seo_checks/<name>.py, rename it to check(site) (use site.pages, site.home or site.public_dir), move its constants and helpers with it, give it a docstring, move its tests to scripts/tests/test_seo_<name>.py, and drop its line from results and the numbered docstring list.

The SEO unit tests still don't run in CI; that is tracked in https://github.com/forrtproject/forrtproject.github.io/issues/1223.

Created with Claude Opus 5.5 in Claude Code (T3 Code); options reviewed by GPT-6.2 Sol in Codex.