Project write-up

Preflight Checker

A PowerShell 7 script that checks this site before it ships, and a GitHub Action that runs it on every push and pull request.

The problem

This site is plain HTML with no build step, so nothing stops a mistake from shipping. A broken link, a page with no description, or a 4 MB photo would go live, and I'd only find out when someone else did.

Constraints

  • No build step, no npm. The site is plain HTML and CSS.
  • PowerShell 7, so it runs the same on Windows and on the Linux GitHub Actions runner.
  • Exit codes CI can read: 0 pass, 1 fail, 2 bad input.

What I built

Excerpt of a Preflight report in a terminal, with every page passing.
An excerpt of the report from a passing run.

Invoke-Preflight.ps1 scans every HTML page and image in the site and checks for:

  • Internal links and image sources that don't resolve to a file
  • A missing or empty <title>
  • A missing or empty meta description
  • Images with no alt attribute
  • Image files over 300 KB

It prints a report grouped by file and counts TODO markers as a warning. A GitHub Actions workflow runs PSScriptAnalyzer, the Pester tests, and then Preflight against the site.

I built it with Claude Code as a pair programmer. I set the requirements and the pass/fail rules, Claude Code wrote most of the code, and the tests and CI runs below are how I checked the result.

A few choices I made on purpose:

  • Links resolve the way Cloudflare Pages serves them. projects/x/ means projects/x/index.html, and about also matches about.html. A link that climbs out of the site folder fails, even if the file exists on disk.
  • Markup inside HTML comments is ignored, so a commented-out placeholder doesn't fail the build.
  • TODO markers are counted but don't fail the run. That let me ship a scaffold and still see how much was left.

How I verified it

  • 19 Pester tests, all passing. Each test builds a small throwaway site with one known problem, runs Preflight in a separate process, and checks the exit code and the report text. One clean site has to pass. Every other site has to fail for the right reason.
  • Edge cases are tested, not assumed. An image exactly at 300 KB passes and one at 301 KB fails. An empty href fails. A missing folder or a folder with no pages exits 2, not 0.
  • PSScriptAnalyzer: 0 warnings or errors.
  • In CI: the first push ran lint, tests, and Preflight on the GitHub Actions Linux runner, and the job passed in 38 seconds.

What broke / what I'd change

What broke:

  • Three test names showed up as $null in the output. Pester 6 reads <title> and <img> in a test name as template variables, so I renamed those tests.
  • The first deploy served the whole repo, not just the site, so the scripts and a notes file meant only for the repo were public too. I moved the site into /site, pointed Cloudflare Pages at that folder, and now Preflight runs against ./site.

What I'd change:

  • HTML is matched with regular expressions, not a full parser. That works for pages I write by hand, but it would break on unusual markup.
  • Windows paths aren't case-sensitive, so a link with the wrong case passes locally. The Linux CI run catches it, but a local check would be faster.
  • External links aren't checked. A scheduled weekly run for those would catch link rot without slowing down every push.
  • Source code: coming soon as a public repo.
  • Pester, the PowerShell test framework
  • PSScriptAnalyzer, the PowerShell linter