Skip to content

Check the site before it is served - #2

Merged
marcos-mendez merged 2 commits into
mainfrom
ci/site-check
Sep 26, 2026
Merged

marcos-mendez merged 2 commits into
mainfrom
ci/site-check

Conversation

@marcos-mendez

Copy link
Copy Markdown
Contributor

The site had no gate. Nothing builds it, so a link that resolves to nothing,
an asset that was removed or an external link over plain HTTP went straight to
the public page with nobody in the way. It is the most visible repository in
the organization and the only active one with no required check.

tools/sitecheck.py does what a build step would have done: internal links
resolve, fragments name ids that exist (including on another page), every
referenced asset exists and every asset is referenced (counting the og:image
and twitter:image cards a crawler fetches), external links are https or
mailto, and each page has a language, a title and exactly one h1.

Two findings from the first run were real: the dark and one-colour marks were
served and referenced by nothing. guidelines.html now has a section for the
mark offering all four variants with the rules for using them.

Test plan

  • 37 tests, one per rule, each stated as the smallest page that breaks it.
  • The suite ends by running the checker over this repository, so the gate
    fails on a real broken link rather than only on a unit case.
  • tools/sitecheck.py 99 percent lines and branches, against the 95 the
    project asks of its own code.
  • python3 tools/sitecheck.py . exits 0 on this branch: 2 pages, 7 assets,
    0 findings.
  • After merge: make python / coverage required on main.

The site had no gate at all. Nothing builds it, so a link that resolves to
nothing, an asset that was removed or an external link over plain HTTP went
straight to the public page with nobody in the way. Every other repository in
the organization has a required check; this one is the most visible and had
none.

tools/sitecheck.py is what a build step would have done:

  * every internal link resolves to a file in the repository;
  * every fragment names an id that is on the page it names, including a
    fragment of another page, which is what rots silently when a heading is
    renamed;
  * every referenced asset exists, and every asset in the tree is referenced,
    including the social card of the og:image and twitter:image meta tags,
    which a crawler fetches and a reader never sees fail;
  * an external link is https or mailto;
  * a page carries a language, a title and exactly one h1.

It is a pure function of a mapping of path to text, so each rule is tested as
the smallest page that breaks it, and the suite ends by running the checker
over this repository: the rules are only worth having if the site satisfies
them.

Two findings came out of the first run, both real. The dark and the one
colour marks were served and referenced by nothing, so guidelines.html now
has a section for the mark that offers all four variants with the rules for
using them, which is what a brand page is for.

Measured: 37 tests, tools/sitecheck.py 99 percent lines and branches, against
the 95 the project asks of its own code.
The gate failed on its first run, correctly, and on something the local run
could not see: in CI the editable install writes *.egg-info/SOURCES.txt and
its siblings into the tree, and a .txt is something a site can legitimately
serve, so three packaging files were counted as assets no page references.

A suffix rule alone cannot tell them apart, so the tree now says which
directories are the site: this checker, its tests, and the directories a tool
leaves behind are not, including anything ending in .egg-info or .dist-info.
Tested against a fixture tree carrying all four.

.gitignore keeps the same leftovers out of the repository.
@marcos-mendez
marcos-mendez merged commit 94d2be4 into main Sep 26, 2026
1 check passed
@marcos-mendez
marcos-mendez deleted the ci/site-check branch September 26, 2026 21:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant