ci.yml

name: CI

on:
  # Only main, because every other branch reaches this through a pull request
  # and would otherwise run the whole suite twice for one change. Measured on
  # pull request 4, the first one this project had: every job appeared twice,
  # once for the branch push and once for the pull request, and the race
  # detector ran both times at about ten minutes each.
  #
  # The cost of the narrower trigger is that pushing a branch with no pull
  # request open gives no signal. Since 2026-08-27 main only takes pull
  # requests, so that state is a step on the way rather than a place work sits.
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:
  schedule:
    # Weekly, for the fuzzing job below only. Every other job here runs on
    # push, and fuzzing deliberately does not - see that job for why.
    - cron: "17 4 * * 1"

permissions:
  contents: read

env:
  # The exact toolchain used for tests and releases. go.mod declares a
  # minimum - this is the pin. Raising it can change generated bytes, so the
  # byte stability guard has to be green before it moves.
  GO_VERSION: "1.27.4"

jobs:
  test:
    name: test on ${{ matrix.os }}
    # A hung job otherwise holds a runner until the GitHub default of six
    # hours. Remeasured 2026-09-03, because the sentence here said "the matrix
    # runs in about a minute" and had not been true for a long time: the test
    # step alone takes 399 s on ubuntu, 476 s on windows and 491 s on macOS.
    # The race detector took 148 s when it was measured and has its own job
    # and its own numbers now, and fuzzing is given 5 minutes a target by its
    # own loop.
    timeout-minutes: 20
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    env:
      # The engine, the command line and the tests build without CGO on every
      # system. Only the desktop window needs a C compiler, and it is built
      # separately.
      #
      # macOS is the exception and it is the toolkit's, not ours. Measured on
      # 2026-08-20, the first run this matrix had since the toolkit arrived:
      # with CGO off, vet cannot type check fyne's own internal/widget on
      # darwin - subscribeScrollerStyle and three others are undefined, because
      # the file defining them is behind a build tag that CGO off removes.
      # Nothing of ours is involved and there is nothing of ours to fix, so that
      # one runner pays for a C toolchain it already has.
      CGO_ENABLED: ${{ matrix.os == 'macos-latest' && '1' || '0' }}
      # The one guard that builds the window WITH cgo is read by the imports
      # job below instead, and this asks it to skip here. Measured 2026-09-17:
      # with CGO off, nothing else in this job compiles the OpenGL binding or
      # GLFW, so that guard was the run's one cold cgo build - 822 s for the
      # Windows test step against 434 s warm, four minutes under the timeout,
      # and cold again after every change to go.sum. The variable is named in
      # exactly one place, internal/guard/noimport_test.go, and a guard there
      # holds this job to setting it and the imports job to not setting it.
      TFG_IMPORT_TABLE_JOB: "1"
    steps:
      # Every checkout in these workflows turns the token off. The checkout
      # keeps the job's token in .git/config unless told not to, and the jobs
      # go on to run code from the pull request under test. Nothing after a
      # checkout here pushes or fetches - the release and the pages talk to
      # GitHub through gh and through actions that carry their own token - so
      # the credential has no use once the tree is on disk. A guard asks each
      # checkout (checkoutcredentials_test.go), so a new one cannot forget.
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e  # v7.0.0
        with:
          go-version: ${{ env.GO_VERSION }}
          check-latest: false
          # Keyed on go.sum. The one dependency is the YAML parser behind the
          # recipe - see docs/STACK.md.
          cache: true

      - name: formatting
        run: |
          test -z "$(gofmt -l .)" || { echo "gofmt found unformatted files:"; gofmt -l .; exit 1; }
        shell: bash

      - name: vet
        run: go vet -tags "$(cat .github/build-tags)" ./...

      - name: the dependency list has not grown by accident
        # Every dependency is a licence question and a byte stability
        # question. A new one arriving as somebody's transitive import has
        # to be visible rather than discovered later.
        #
        # Two questions rather than one, since the graphics toolkit arrived
        # on 2026-08-05. The graph below is 65 modules and most of them are
        # Fyne's. Their licences were measured before it was added and every
        # one in the linked set is permissive and one way compatible with
        # GPL-3.0: 13 BSD-3, 9 MIT, 1 Apache-2.0, 1 BSD-2, 1 ISC.
        #
        # Changed once since, on 2026-08-05, when the window gained a
        # folder picker. github.com/FyshOS/fancyfs was already named here
        # because the toolkit requires it - importing the dialog package
        # moved it from named to downloaded, checksummed and compiled in.
        # Checked before it was accepted: BSD-3, 129 lines, written by the
        # toolkit's own author, and reached from one line of the dialog
        # package where it decorates folder icons. Tidying after it pruned
        # github.com/kr/text from go.mod, which took github.com/creack/pty
        # out of the graph, taking the count from 69 to 68.
        #
        # Changed again on 2026-08-27, when the toolkit went to 2.8.1. Three
        # modules left the graph and none of them was ours to begin with -
        # github.com/felixge/fgprof, github.com/google/pprof and
        # github.com/pkg/profile all arrived through Fyne's own tooling and
        # that release no longer asks for them, taking the count from 68 to
        # 65. A fourth, github.com/fredbi/uri, stayed in the graph and left
        # the linked set instead: 2.8.1 parses addresses itself. That is the
        # difference these two questions exist to keep apart, so it is worth
        # saying which one moved - the notices file tracks the linked set and
        # dropped it, this list tracks the graph and keeps it.
        #
        # Changed on 2026-08-31 by a Dependabot bump, and it is the exact case
        # the second paragraph of .github/dependabot.yml warns about. Taking
        # github.com/nicksnyder/go-i18n/v2 from 2.5.1 to 2.6.1 pulled a module
        # nobody asked for into the graph: go.yaml.in/yaml/v3, which is the
        # same yaml library as gopkg.in/yaml.v3 under the module path that
        # project moved to. Both are in the graph now, because other modules
        # still ask for the old path.
        #
        # Its licence was read from the pinned version rather than off a web
        # page: LICENSE is MIT and Apache-2.0 together - the files ported from
        # libyaml keep the MIT of the original C, the rest is Apache-2.0 with a
        # NOTICE from Canonical - and both are one way compatible with GPL-3.0.
        # It is in the GRAPH and linked into NEITHER binary, which is the
        # distinction these two questions exist to keep apart, so it belongs
        # here and not in the notices. The count went 67 to 68.
        #
        # Changed on 2026-08-29 when AVIF arrived, and again on 2026-08-31
        # when JPEG XL did: github.com/gen2brain/gav1d and then
        # github.com/gen2brain/jxl, both picture encoders written in Go with
        # empty go.mod files of their own, so neither brought anything else
        # into the graph. Both licences were read out of the pinned module
        # rather than off a web page - BSD-2-Clause with an AOM patent grant,
        # and BSD-3-Clause with a Google patent grant - and both are one way
        # compatible with GPL-3.0. The count went 65 to 66 to 67.
        #
        # Worth saying plainly, because it is the failure this comment exists
        # to prevent: the sentence above went stale on 2026-08-29 and nobody
        # noticed. It still said 65 while the list held 66, because AVIF
        # updated the list and not the prose. The list is checked by the job
        # below and the prose is checked by nobody.
        #
        # Unchanged on 2026-09-17, when github.com/go-gl/gl gained a replace
        # directive pointing at a copy under third_party, and that is worth
        # saying because it looks like the kind of change this list exists to
        # notice. go list still reports the module under its own path, so
        # the list below is the same - what moved is where the bytes come
        # from, and two guards hold that instead: one keeps the copy equal to
        # the published version plus exactly the one patch its PATCH.md
        # describes, and one reads the built window binary's import table.
        # go.sum no longer carries the module's sum, because a replaced
        # module has none there. The sum lives in that PATCH.md now.
        #
        # The second question protects what ships to most people. The
        # command line binary links exactly four external modules and the
        # toolkit is not among them, so a build for a server carries no
        # window, no OpenGL and - see internal/guard - no socket.
        #
        # Five on Linux and macOS since 2026-09-29 (O252): golang.org/x/sys,
        # for the one call that gives a finished file its name without
        # replacing anything there - renameat2 with RENAME_NOREPLACE and
        # renamex_np with RENAME_EXCL. Already in the graph at the same
        # version, BSD-3-Clause read from its LICENSE file. Not on Windows:
        # golang.org/x/sys/windows imports net, which the command line may not
        # link, so Windows makes the same call through syscall. The answer
        # therefore depends on the runner, and the list says so.
        run: |
          set -euo pipefail
          # Built with printf rather than written across several lines. A
          # continuation starting in column one reads as the end of the jobs
          # block to anything scanning this file by indentation, and the
          # guard on job timeouts does exactly that - it counted one job
          # instead of seven and went green whatever it was given.
          expected=$(printf '%s\n' \
            fyne.io/fyne/v2 \
            fyne.io/systray \
            github.com/BurntSushi/toml \
            github.com/FyshOS/fancyfs \
            github.com/akavel/rsrc \
            github.com/anthonynsimon/bild \
            github.com/clipperhouse/uax29/v2 \
            github.com/cpuguy83/go-md2man/v2 \
            github.com/davecgh/go-spew \
            github.com/fogleman/gg \
            github.com/fredbi/uri \
            github.com/fsnotify/fsnotify \
            github.com/fyne-io/gl-js \
            github.com/fyne-io/glfw-js \
            github.com/fyne-io/image \
            github.com/fyne-io/oksvg \
            github.com/gen2brain/gav1d \
            github.com/gen2brain/jxl \
            github.com/go-gl/gl \
            github.com/go-gl/glfw/v3.4/glfw \
            github.com/go-ole/go-ole \
            github.com/go-text/render \
            github.com/go-text/typesetting \
            github.com/go-text/typesetting-utils \
            github.com/goccy/go-yaml \
            github.com/godbus/dbus/v5 \
            github.com/golang/freetype \
            github.com/hack-pad/go-indexeddb \
            github.com/hack-pad/safejs \
            github.com/inconshreveable/mousetrap \
            github.com/jackmordaunt/icns/v2 \
            github.com/jeandeaual/go-locale \
            github.com/josephspurrier/goversioninfo \
            github.com/jsummers/gobmp \
            github.com/kr/text \
            github.com/lucor/goinfo \
            github.com/mattn/go-runewidth \
            github.com/mcuadros/go-version \
            github.com/natefinch/atomic \
            github.com/nfnt/resize \
            github.com/nicksnyder/go-i18n/v2 \
            github.com/niemeyer/pretty \
            github.com/pmezard/go-difflib \
            github.com/russross/blackfriday/v2 \
            github.com/rymdport/portal \
            github.com/spf13/cobra \
            github.com/spf13/pflag \
            github.com/srwiley/oksvg \
            github.com/srwiley/rasterx \
            github.com/stretchr/objx \
            github.com/stretchr/testify \
            github.com/urfave/cli/v2 \
            github.com/xrash/smetrics \
            github.com/yuin/goldmark \
            go.yaml.in/yaml/v3 \
            golang.org/x/crypto \
            golang.org/x/image \
            golang.org/x/mobile \
            golang.org/x/mod \
            golang.org/x/net \
            golang.org/x/sync \
            golang.org/x/sys \
            golang.org/x/term \
            golang.org/x/text \
            golang.org/x/tools \
            golang.org/x/tools/go/vcs \
            gopkg.in/check.v1 \
            gopkg.in/yaml.v3)
          # LC_ALL=C on every sort here, and on the written list too. Measured on
          # 2026-08-20, the first run this job ever had on macOS: both lists
          # held the same 68 modules and the comparison still failed, because
          # BSD sort and GNU sort disagree about where a hyphen goes. The check
          # is a string comparison, so an ordering difference reads exactly like
          # a dependency appearing out of nowhere.
          expected=$(printf '%s\n' "$expected" | LC_ALL=C sort)
          actual=$(go list -m -f '{{.Path}}' all | grep -v '^github.com/donislawdev/TestingFilesGenerator$' | LC_ALL=C sort)
          if [ "$actual" != "$expected" ]; then
            echo "the module list changed."
            echo "expected: $expected"
            echo "actual  : $actual"
            exit 1
          fi
          echo "dependencies unchanged, $(echo "$expected" | wc -l) modules"

          linked=$(go list -deps -tags "$(cat .github/build-tags)" -f '{{if .Module}}{{.Module.Path}}{{end}}' ./cmd/tfg | LC_ALL=C sort -u | grep -v '^github.com/donislawdev/TestingFilesGenerator$' | grep .)
          wanted=$(printf '%s\n' github.com/gen2brain/gav1d github.com/gen2brain/jxl github.com/goccy/go-yaml golang.org/x/text)
          if [ "$RUNNER_OS" != "Windows" ]; then
            wanted=$(printf '%s\n' $wanted golang.org/x/sys | LC_ALL=C sort)
          fi
          if [ "$linked" != "$wanted" ]; then
            echo "the command line binary links a different set of modules."
            echo "expected: $wanted"
            echo "actual  : $linked"
            exit 1
          fi
          echo "the command line binary links only: $linked"
        shell: bash

      - name: test
        # The timeout is stated for the reason the race job and the coverage
        # gate both state theirs: Go allows ten minutes PER PACKAGE by default,
        # this job allows twenty for all of it, and internal/guard is one
        # package holding almost every test there is. A run that went past the
        # first without approaching the second would die as a stack trace out
        # of whichever test happened to be running, which is what the coverage
        # gate did on 2026-09-03.
        #
        # Measured that day, on the run that caught it: 399 s on ubuntu, 476 s
        # on windows, 491 s on macOS. macOS therefore had 109 s of room under a
        # limit nobody had chosen, and the same fleet was measured swinging by
        # more than 25 percent between two runs of one branch.
        run: go test -tags "$(cat .github/build-tags)" ./... -count=1 -timeout 18m

      - name: build the command line binary
        run: go build -tags "$(cat .github/build-tags)" ./cmd/tfg

      - name: build the window binary
        # The toolkit arrived on 2026-08-05 and this step still passes, which
        # is the point of how it was wired in. Reaching the toolkit's app
        # package needs CGO and, on Linux, X11 development headers no runner
        # carries by default - so that one file sits behind a cgo build tag and
        # everything building a widget tree sits outside it.
        #
        # On Linux and Windows CGO_ENABLED is 0, so this proves the tree still
        # compiles where there is no compiler and no graphics. The tests go
        # further: they render a screen to an image and read it, also with CGO
        # off.
        #
        # On macOS it proves something else, and better - the windowed binary
        # actually LINKS. That runner has CGO on because the toolkit cannot be
        # type checked on darwin without it, so the build here is the real one.
        # Which closes half of the gap this comment used to name: linking was
        # done natively and nowhere but on the owner's machine.
        #
        # The flags below are Windows only. -H windowsgui names a Windows
        # subsystem, and handing it to the darwin linker is what turned this
        # step red on 2026-08-20 the moment macOS gained a C toolchain.
        #
        # The linker flags come from the file rather than from this line, so
        # that the release build and this one cannot drift apart. The file is
        # the single place they live, the same way the coverage threshold is.
        # Without them Windows attaches a console window to the program, which
        # it decides from one number in the PE header - and that number is what
        # the guard reads, out of a binary it builds rather than out of this
        # command.
        run: |
          set -euo pipefail
          if [ "$RUNNER_OS" = "Windows" ]; then
            go build -tags "$(cat .github/build-tags)" -ldflags="$(cat .github/gui-ldflags)" ./cmd/tfg-gui
          else
            go build -tags "$(cat .github/build-tags)" ./cmd/tfg-gui
          fi
        shell: bash

  imports:
    name: import table of the window binary
    # One guard, in a job of its own, because it is the one guard that builds
    # the window WITH cgo: TestTheWindowBinaryDoesNotImportOpenGLAtLoadTime
    # links tfg-gui.exe the way a release does and reads its import table,
    # which is how the software renderer's whole premise is held (O218). In
    # the test matrix that build was the run's only cold cgo build - measured
    # 2026-09-17, 822 s for the Windows test step against 434 s warm, four
    # minutes under the timeout, and cold again after every change to go.sum,
    # which is every Dependabot pull request. The matrix asks the guard to
    # skip there (TFG_IMPORT_TABLE_JOB), and this job runs it.
    #
    # The cache is this job's own. setup-go keys its cache on the hash of the
    # files named here (source of v7.0.0, cache-restore.ts), and the matrix
    # job on the same runner keys on go.sum alone. Under one key the matrix
    # would save first, without a single cgo object, and this job would pay
    # the cold build on every run. The second file is the sum of the patched
    # OpenGL binding, which is what the cgo build actually compiles - so the
    # key moves when either input to those objects does.
    #
    # Two things make the step fail rather than pass on nothing, and both were
    # measured before they were written: go test with a -run pattern that
    # matches no test exits 0 saying "no tests to run", and the guard skips
    # with exit 0 on a runner without gcc. So the log is read for the PASS
    # line of the one test this job exists for, under pipefail so a failing
    # go test is not hidden behind tee. The name in the pattern is held equal
    # to the function in internal/guard/noimport_test.go by a guard.
    runs-on: windows-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e  # v7.0.0
        with:
          go-version: ${{ env.GO_VERSION }}
          check-latest: false
          cache: true
          cache-dependency-path: |
            go.sum
            third_party/go-gl-gl/PATCH.md

      - name: the window binary imports no opengl32.dll at load time
        run: |
          set -euo pipefail
          go test -tags "$(cat .github/build-tags)" ./internal/guard/ -count=1 -run '^TestTheWindowBinaryDoesNotImportOpenGLAtLoadTime$' -v -timeout 12m 2>&1 | tee import-table.log
          grep -q -- '--- PASS: TestTheWindowBinaryDoesNotImportOpenGLAtLoadTime' import-table.log
        shell: bash

  packages:
    name: the Chocolatey packages install and leave
    # What the packages DO, asked on a clean Windows machine rather than read
    # off their text. The guards in internal/guard/packaging_test.go hold the
    # lines that matter, and they check that a line is there - which is not the
    # same as the install working (docs/PACKAGING-2026-09-25.md section 8.5).
    # This job renders both Chocolatey packages from the latest published
    # release, installs them the way a person does - the archives come from
    # the release page and are checked against its checksums - and asks the
    # machine what happened: the command answers with the version, the window's
    # shim does not wait, the software renderer lies beside the window, the
    # Start menu shortcut starts in the user's profile. Then it removes them and
    # asks again, including whether a shortcut of somebody else's under the same
    # name was left alone - by the uninstall, and by an install that found it
    # there, which is what the program's Windows installer leaves.
    #
    # Against the LATEST release, because a package can only point at one that
    # exists. A change that renames the archives in release.yml will fail here
    # until a release with the new names is published, and that is the right
    # answer: the packages cannot be submitted before it either. Chocolatey
    # only (--only chocolatey): the window's WinGet package needs the release's
    # Windows installer, which releases before it was added do not have, and
    # WinGet is not installed here anyway.
    #
    # WinGet is not asked here. The runner image does not carry it - its own
    # inventory lists Chocolatey 2.7.4 and no WinGet (Windows2025-Readme.md,
    # read 2026-09-25) - so both WinGet manifests are validated and installed on
    # a virtual machine before every submission instead.
    runs-on: windows-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
        with:
          python-version: "3.14"

      - name: render the packages for the latest release
        id: render
        shell: pwsh
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          $ErrorActionPreference = 'Stop'
          $tag = gh release view --json tagName --jq .tagName
          if ($LASTEXITCODE -ne 0 -or -not $tag) { throw "could not read the latest release" }
          gh release download $tag --pattern verify-SHA256SUMS.txt --dir $env:RUNNER_TEMP
          if ($LASTEXITCODE -ne 0) { throw "could not download the checksums of $tag" }
          python .github/scripts/build_packages.py --tag $tag `
            --sums (Join-Path $env:RUNNER_TEMP 'verify-SHA256SUMS.txt') `
            --out (Join-Path $env:RUNNER_TEMP 'packages') --only chocolatey
          if ($LASTEXITCODE -ne 0) { throw "the renderer refused $tag" }
          "version=$($tag.TrimStart('v'))" >> $env:GITHUB_OUTPUT

      - name: install both, ask the machine, remove both, ask again
        shell: pwsh
        env:
          VERSION: ${{ steps.render.outputs.version }}
        run: |
          $ErrorActionPreference = 'Stop'
          $failed = 0
          function Check($ok, $what) {
            if ($ok) { "ok      $what" } else { "FAILED  $what"; $script:failed++ }
          }

          $feed = Join-Path $env:RUNNER_TEMP 'feed'
          New-Item -ItemType Directory -Force $feed | Out-Null
          foreach ($id in 'testing-files-generator', 'testing-files-generator-cli') {
            $nuspec = Join-Path $env:RUNNER_TEMP "packages\chocolatey\$id\$id.nuspec"
            choco.exe pack $nuspec --outputdirectory $feed
            if ($LASTEXITCODE -ne 0) { throw "choco pack $id exited $LASTEXITCODE" }
          }
          choco.exe install testing-files-generator testing-files-generator-cli --source $feed --yes --no-progress
          if ($LASTEXITCODE -ne 0) { throw "choco install exited $LASTEXITCODE" }

          $bin = Join-Path $env:ChocolateyInstall 'bin'
          $lib = Join-Path $env:ChocolateyInstall 'lib'
          $window = Join-Path $lib 'testing-files-generator\tools\tfg-gui\tfg-gui.exe'
          $cli = Join-Path $lib 'testing-files-generator-cli\tools\tfg\tfg.exe'
          $shortcut = Join-Path ([Environment]::GetFolderPath('CommonPrograms')) 'Testing Files Generator.lnk'

          $installed = (choco.exe list --limit-output) -join "`n"
          Check ($installed -match "(?m)^testing-files-generator\|$([regex]::Escape($env:VERSION))$") "the window package is installed at $env:VERSION"
          Check ($installed -match "(?m)^testing-files-generator-cli\|$([regex]::Escape($env:VERSION))$") "the command line package is installed at $env:VERSION"

          $said = (& (Join-Path $bin 'tfg.exe') version) -join ''
          Check ($LASTEXITCODE -eq 0 -and $said.Trim() -eq $env:VERSION) "tfg version answers $env:VERSION through the shim (said '$said')"

          # The shim describes itself without starting anything. Measured
          # 2026-09-25: it names its target and says GUI 'True' only when the
          # .gui file lay beside the program when the shim was made.
          $cliShim = (& (Join-Path $bin 'tfg.exe') --shimgen-help 2>&1) -join "`n"
          Check ($cliShim -match "GUI: 'False'" -and $cliShim.Contains($cli)) "the tfg shim waits for the command line, so a script reads its exit code"
          $windowShim = (& (Join-Path $bin 'tfg-gui.exe') --shimgen-help 2>&1) -join "`n"
          Check ($windowShim -match "GUI: 'True'" -and $windowShim.Contains($window)) "the tfg-gui shim does not hold the terminal"

          foreach ($file in 'opengl32.dll', 'libgallium_wgl.dll') {
            Check (Test-Path (Join-Path (Split-Path $window) "opengl\$file")) "the software renderer's $file lies beside the window"
          }

          $shell = New-Object -ComObject WScript.Shell
          Check (Test-Path $shortcut) "the Start menu shortcut is there"
          $link = $shell.CreateShortcut($shortcut)
          Check ($link.TargetPath -eq $window) "the shortcut starts the window (it starts '$($link.TargetPath)')"
          Check ($link.WorkingDirectory -eq '%USERPROFILE%') "the shortcut starts in the user's profile (it starts in '$($link.WorkingDirectory)')"

          choco.exe uninstall testing-files-generator-cli --yes --no-progress
          if ($LASTEXITCODE -ne 0) { throw "choco uninstall of the command line exited $LASTEXITCODE" }
          Check (-not (Test-Path (Join-Path $bin 'tfg.exe'))) "removing the command line takes its shim"
          Check (-not (Test-Path (Split-Path $cli))) "removing the command line takes its files"

          # A shortcut of somebody else's under the same name, made after the
          # install, must survive the uninstall - one pointing at a file, and
          # one pointing at a shell item, which answers with an empty path.
          $other = $shell.CreateShortcut($shortcut)
          $other.TargetPath = Join-Path $env:WINDIR 'notepad.exe'
          $other.Save()
          $said = (choco.exe uninstall testing-files-generator --yes --no-progress) -join "`n"
          if ($LASTEXITCODE -ne 0) { throw "choco uninstall of the window exited $LASTEXITCODE" }
          Check (Test-Path $shortcut) "a shortcut that points at another file is left alone"
          Check ($said -match 'It points at .*notepad\.exe, not at this package') "and the uninstall says where it points"
          Remove-Item -LiteralPath $shortcut -Force
          Check (-not (Test-Path (Join-Path $bin 'tfg-gui.exe'))) "removing the window takes its shim"
          Check (-not (Test-Path (Split-Path $window))) "removing the window takes its files"

          choco.exe install testing-files-generator --source $feed --yes --no-progress
          if ($LASTEXITCODE -ne 0) { throw "the second install exited $LASTEXITCODE" }
          $other = $shell.CreateShortcut($shortcut)
          $other.TargetPath = '::{20D04FE0-3AEA-1069-A2D8-08002B30309D}'
          $other.Save()
          Check ($shell.CreateShortcut($shortcut).TargetPath -eq '') "a shortcut to a shell item answers with an empty path"
          $said = (choco.exe uninstall testing-files-generator --yes --no-progress) -join "`n"
          if ($LASTEXITCODE -ne 0) { throw "the second uninstall exited $LASTEXITCODE" }
          Check (Test-Path $shortcut) "a shortcut that points at a shell item is left alone"
          Check ($said -match 'It points at no file, so it is not from this package') "and the uninstall says so in a whole sentence"
          Remove-Item -LiteralPath $shortcut -Force

          # And the ordinary case: install again, uninstall, and the package's
          # own shortcut goes with it.
          choco.exe install testing-files-generator --source $feed --yes --no-progress
          if ($LASTEXITCODE -ne 0) { throw "the third install exited $LASTEXITCODE" }
          Check (Test-Path $shortcut) "installing again makes the shortcut again"
          choco.exe uninstall testing-files-generator --yes --no-progress
          if ($LASTEXITCODE -ne 0) { throw "the third uninstall exited $LASTEXITCODE" }
          Check (-not (Test-Path $shortcut)) "removing the window takes its own shortcut"

          # A shortcut of another install already there when the package comes
          # - the program's Windows installer makes one under this very name -
          # is left alone by the install, and so by the uninstall. So is one to
          # a shell item, which points at no file. One whose target is gone
          # belongs to nobody, and the install replaces it.
          $notepad = Join-Path $env:WINDIR 'notepad.exe'
          $other = $shell.CreateShortcut($shortcut)
          $other.TargetPath = $notepad
          $other.Save()
          $said = (choco.exe install testing-files-generator --source $feed --yes --no-progress) -join "`n"
          if ($LASTEXITCODE -ne 0) { throw "the fourth install exited $LASTEXITCODE" }
          Check ($shell.CreateShortcut($shortcut).TargetPath -eq $notepad) "the install leaves a shortcut of another install alone"
          Check ($said -match 'It points at .*notepad\.exe, not at this package') "and the install says where it points"
          choco.exe uninstall testing-files-generator --yes --no-progress
          if ($LASTEXITCODE -ne 0) { throw "the fourth uninstall exited $LASTEXITCODE" }
          Check ($shell.CreateShortcut($shortcut).TargetPath -eq $notepad) "and so does the uninstall"
          Remove-Item -LiteralPath $shortcut -Force
          $other = $shell.CreateShortcut($shortcut)
          $other.TargetPath = '::{20D04FE0-3AEA-1069-A2D8-08002B30309D}'
          $other.Save()
          $said = (choco.exe install testing-files-generator --source $feed --yes --no-progress) -join "`n"
          if ($LASTEXITCODE -ne 0) { throw "the shell item install exited $LASTEXITCODE" }
          Check ((Test-Path $shortcut) -and $shell.CreateShortcut($shortcut).TargetPath -eq '') "the install leaves a shortcut to a shell item alone"
          Check ($said -match 'It points at no file, so it is not from this package') "and the install says so in a whole sentence"
          choco.exe uninstall testing-files-generator --yes --no-progress
          if ($LASTEXITCODE -ne 0) { throw "the shell item uninstall exited $LASTEXITCODE" }
          Check ((Test-Path $shortcut) -and $shell.CreateShortcut($shortcut).TargetPath -eq '') "and so does the uninstall"
          Remove-Item -LiteralPath $shortcut -Force
          $other = $shell.CreateShortcut($shortcut)
          $other.TargetPath = Join-Path $env:RUNNER_TEMP 'gone\tfg-gui.exe'
          $other.Save()
          choco.exe install testing-files-generator --source $feed --yes --no-progress
          if ($LASTEXITCODE -ne 0) { throw "the fifth install exited $LASTEXITCODE" }
          Check ($shell.CreateShortcut($shortcut).TargetPath -eq $window) "the install replaces a shortcut whose target is gone"
          choco.exe uninstall testing-files-generator --yes --no-progress
          if ($LASTEXITCODE -ne 0) { throw "the fifth uninstall exited $LASTEXITCODE" }
          Check (-not (Test-Path $shortcut)) "and the uninstall takes the shortcut it made"

          if ($failed -ne 0) { throw "$failed check(s) failed - read the FAILED lines above" }
          "every check passed"

  installer:
    name: the installer installs and leaves
    # What the Windows installer DOES, asked on a clean Windows machine rather
    # than read off its source. The guards in internal/guard/msi_test.go hold
    # the lines each measurement rests on, and a line being there is not the
    # install working (docs/PACKAGING-2026-09-25.md section 13). The installer
    # is built unsigned here, from the latest published release's two amd64
    # archives - checked against its checksums - and this commit's template,
    # the way sign_release.py builds the signed one from a tag. It is
    # installed silently and asked what it did, built again and installed over
    # itself while a tfg run is in progress, and removed with a file of
    # somebody else's in its folder.
    #
    # Against the latest release for the reason the job above gives: the
    # archives are the ones a person downloads. The upgrade from one version
    # to the next needs two published installers, so it was measured on a
    # virtual machine instead, 0.3.0 to 0.4.0 (tools/packaging-vm).
    runs-on: windows-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
        with:
          python-version: "3.14"

      - name: build the installer twice from the latest release
        id: build
        shell: pwsh
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          $ErrorActionPreference = 'Stop'
          # The WiX this project builds with. build_msi.py refuses any other,
          # and finds it in the dotnet tools folder without a PATH change.
          dotnet tool install --global wix --version 5.0.2
          if ($LASTEXITCODE -ne 0) { throw "could not install WiX 5.0.2" }
          $tag = gh release view --json tagName --jq .tagName
          if ($LASTEXITCODE -ne 0 -or -not $tag) { throw "could not read the latest release" }
          $archives = Join-Path $env:RUNNER_TEMP 'archives'
          gh release download $tag --dir $archives --pattern 'tfg_*_windows_amd64.zip' --pattern 'tfg-gui_*_windows_amd64.zip' --pattern verify-SHA256SUMS.txt
          if ($LASTEXITCODE -ne 0) { throw "could not download the archives of $tag" }
          $sums = Get-Content (Join-Path $archives 'verify-SHA256SUMS.txt')
          foreach ($zip in Get-ChildItem $archives -Filter '*.zip') {
            $got = (Get-FileHash $zip.FullName -Algorithm SHA256).Hash.ToLower()
            if (-not ($sums -contains ($got + '  ' + $zip.Name))) { throw "$($zip.Name) does not match the checksums of $tag" }
          }
          # Twice, because every build carries a new ProductCode - the second
          # is the same version rebuilt, as a feed's moderation may ask for.
          foreach ($build in 'first', 'second') {
            $out = Join-Path $env:RUNNER_TEMP $build
            New-Item -ItemType Directory -Force $out | Out-Null
            python .github/scripts/build_msi.py --tag $tag --archives $archives --out-dir $out
            if ($LASTEXITCODE -ne 0) { throw "build_msi.py refused $tag" }
          }
          "version=$($tag.TrimStart('v'))" >> $env:GITHUB_OUTPUT

      - name: install, ask the machine, install again while tfg runs, remove, ask again
        shell: pwsh
        env:
          VERSION: ${{ steps.build.outputs.version }}
        run: |
          $ErrorActionPreference = 'Stop'
          $failed = 0
          function Check($ok, $what) {
            if ($ok) { "ok      $what" } else { "FAILED  $what"; $script:failed++ }
          }
          $name = 'Testing Files Generator'
          $dir = Join-Path $env:ProgramFiles $name
          $shortcut = Join-Path ([Environment]::GetFolderPath('CommonPrograms')) "$name.lnk"
          $archives = Join-Path $env:RUNNER_TEMP 'archives'
          $first = (Get-ChildItem (Join-Path $env:RUNNER_TEMP 'first') -Filter '*.msi').FullName
          $second = (Get-ChildItem (Join-Path $env:RUNNER_TEMP 'second') -Filter '*.msi').FullName

          # The arguments in a variable and a limit on the wait: a quote that
          # swallows the file name leaves msiexec waiting on a help window.
          function Msi($verb, $file, $log) {
            $argv = @($verb, "`"$file`"", '/qn', '/norestart', '/l*v', "`"$(Join-Path $env:RUNNER_TEMP $log)`"")
            $p = Start-Process -FilePath (Join-Path $env:SystemRoot 'System32\msiexec.exe') -ArgumentList $argv -PassThru
            $null = $p.Handle
            if (-not $p.WaitForExit(600000)) { throw "msiexec $verb did not finish in ten minutes" }
            return $p.ExitCode
          }
          function Entries {
            @(Get-ItemProperty 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*' -ErrorAction SilentlyContinue | Where-Object { $_.DisplayName -eq $name })
          }
          function Listing {
            if (-not (Test-Path -LiteralPath $dir)) { return '(no folder)' }
            (Get-ChildItem -LiteralPath $dir -Recurse -File | ForEach-Object { $_.FullName.Substring($dir.Length + 1).Replace('\', '/') } | Sort-Object) -join ', '
          }
          function OnPath {
            @(([Environment]::GetEnvironmentVariable('Path', 'Machine')).Split(';') | Where-Object { $_.TrimEnd('\') -eq $dir })
          }
          # What the folder has to hold: the two archives, read out of them.
          Add-Type -AssemblyName System.IO.Compression.FileSystem
          $want = (Get-ChildItem $archives -Filter '*.zip' | ForEach-Object {
              $zip = [IO.Compression.ZipFile]::OpenRead($_.FullName)
              try { $zip.Entries | Where-Object { $_.Name } | ForEach-Object { $_.FullName } } finally { $zip.Dispose() }
            } | Sort-Object -Unique) -join ', '
          function Installed {
            $e = @(Entries)
            Check ($e.Count -eq 1 -and $e[0].DisplayVersion -eq $env:VERSION) "one entry in Programs and Features, at $env:VERSION ($(($e | ForEach-Object { $_.DisplayVersion }) -join ', '))"
            Check ((Listing) -eq $want) "the folder holds exactly the two archives ($(Listing))"
            Check (@(OnPath).Count -eq 1) "the folder is on the machine PATH once ($(@(OnPath).Count))"
            Check (-not (Test-Path (Join-Path $dir 'opengl32.dll'))) "opengl32.dll is not in the folder on PATH, where other programs would load it"
            # Asked from a new process, with the PATH a new terminal would read.
            $env:Path = [Environment]::GetEnvironmentVariable('Path', 'Machine') + ';' + [Environment]::GetEnvironmentVariable('Path', 'User')
            $said = ((& cmd.exe /c 'tfg version' 2>&1) | Out-String).Trim()
            Check ($said -eq $env:VERSION) "tfg version, found on PATH, answers $env:VERSION (said '$said')"
            Check (Test-Path $shortcut) "the Start menu has the shortcut, for every account"
            $link = (New-Object -ComObject WScript.Shell).CreateShortcut($shortcut)
            Check ($link.TargetPath -eq (Join-Path $dir 'tfg-gui.exe')) "the shortcut starts the window ($($link.TargetPath))"
            Check ($link.WorkingDirectory.TrimEnd('\') -eq $dir) "the shortcut starts in the install folder, which the window recognises as its own ($($link.WorkingDirectory))"
          }

          Check (@(Entries).Count -eq 0 -and -not (Test-Path $dir) -and @(OnPath).Count -eq 0) "nothing of ours is on the runner before the install"
          $code = Msi '/i' $first 'install.log'
          Check ($code -eq 0) "the installer installs (exit $code)"
          Installed
          $firstCode = @(Entries)[0].PSChildName

          # A tfg run kept in progress without writing to disk: its output goes
          # into a pipe nobody reads, and once the pipe is full it waits.
          $info = [Diagnostics.ProcessStartInfo]::new((Join-Path $dir 'tfg.exe'), 'formats --json')
          $info.UseShellExecute = $false
          $info.RedirectStandardOutput = $true
          $info.CreateNoWindow = $true
          $held = [Diagnostics.Process]::Start($info)
          Start-Sleep -Seconds 2
          Check (-not $held.HasExited) "a tfg run is in progress"
          $code = Msi '/i' $second 'rebuild.log'
          Check ($code -eq 0 -or $code -eq 3010) "the rebuild installs over the first while tfg runs (exit $code)"
          Check (-not $held.HasExited) "the tfg run is still going - nothing ended it"
          [void]$held.StandardOutput.ReadToEnd()
          [void]$held.WaitForExit(10000)
          Check ($held.ExitCode -eq 0) "the tfg run finished with 0 ($($held.ExitCode))"
          Installed
          Check (@(Entries).Count -eq 1 -and @(Entries)[0].PSChildName -ne $firstCode) "the rebuild replaced the first build instead of installing beside it"

          $planted = Join-Path $dir 'somebody-elses.txt'
          Set-Content -LiteralPath $planted -Value 'not ours'
          $code = Msi '/x' $second 'uninstall.log'
          Check ($code -eq 0) "the uninstall succeeds (exit $code)"
          Check (@(Entries).Count -eq 0) "no entry is left in Programs and Features"
          Check ((Listing) -eq 'somebody-elses.txt') "only the file of somebody else is left in the folder ($(Listing))"
          Check (@(OnPath).Count -eq 0) "nothing of ours is left on the machine PATH"
          Check (-not (Test-Path $shortcut)) "the shortcut is gone"
          Check (-not (Test-Path 'HKLM:\Software\DonislawDev')) "nothing of ours is left in the registry"

          if ($failed -ne 0) {
            Get-ChildItem $env:RUNNER_TEMP -Filter '*.log' | ForEach-Object { "--- $($_.Name)"; Get-Content $_.FullName -Tail 40 }
            throw "$failed check(s) failed - read the FAILED lines above"
          }
          "every check passed"

  govulncheck:
    name: known vulnerabilities
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e  # v7.0.0
        with:
          go-version: ${{ env.GO_VERSION }}
          check-latest: false
          cache: true

      - name: the headers the toolkit needs
        # The window reaches OpenGL through C, so anything that builds or
        # analyses the whole tree on Linux compiles GLFW - and no runner carries
        # its headers. Measured on 2026-08-20, the first run after the
        # repository went public and so the first one this job has ever had
        # against the toolkit: "wayland-client-core.h: No such file or
        # directory", and the job never reached our code at all.
        #
        # Taken from the toolkit's own CI rather than from a remembered list.
        run: |
          set -euo pipefail
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends             libgl1-mesa-dev             libwayland-dev             libx11-dev             libxkbcommon-dev             xorg-dev
        shell: bash

      - name: govulncheck
        # The official Go vulnerability scanner. BSD-3-Clause, read from the
        # LICENSE file of the pinned version rather than recalled. Run rather
        # than imported, so it never enters go.mod.
        #
        # It reports only what is actually reachable from our code, which is
        # what makes it worth having: a scanner that lists every advisory
        # touching the module graph produces noise, and noise gets switched off.
        # Measured before switching it on, 2026-08-02: no vulnerabilities found.
        # v1.8.0 since 2026-09-16, run on the tree before the pin moved: the same
        # verdict as v1.7.0, exit 0 under Go 1.27 - the two pins before this one
        # had stopped working with the compiler without anybody noticing.
        run: go run golang.org/x/vuln/cmd/govulncheck@v1.9.0 -tags "$(cat .github/build-tags)" ./...

  staticcheck:
    name: staticcheck
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e  # v7.0.0
        with:
          go-version: ${{ env.GO_VERSION }}
          check-latest: false
          cache: true

      - name: the headers the toolkit needs
        # The window reaches OpenGL through C, so anything that builds or
        # analyses the whole tree on Linux compiles GLFW - and no runner carries
        # its headers. Measured on 2026-08-20, the first run after the
        # repository went public and so the first one this job has ever had
        # against the toolkit: "wayland-client-core.h: No such file or
        # directory", and the job never reached our code at all.
        #
        # Taken from the toolkit's own CI rather than from a remembered list.
        run: |
          set -euo pipefail
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends             libgl1-mesa-dev             libwayland-dev             libx11-dev             libxkbcommon-dev             xorg-dev
        shell: bash

      - name: staticcheck
        # MIT, pinned. Run rather than imported, so it never enters go.mod and
        # the dependency gate above does not see it - measured twice on
        # 2026-08-02, go.mod and go.sum both untouched afterwards.
        #
        # The version is pinned because an unpinned analyser turns somebody
        # else's release into a red build on a commit that changed nothing.
        #
        # Which checks run, and why ST1005 does not, is in staticcheck.conf.
        # Measured before switching this on: two findings in the whole tree,
        # both of them the word "Pillow" at the start of an error string, which
        # is the name of the library that refused the image rather than a
        # sentence. Zero findings with the config in place.
        run: go run honnef.co/go/tools/cmd/staticcheck@v0.8.2 -tags "$(cat .github/build-tags)" ./...

  lint:
    name: linters
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e  # v7.0.0
        with:
          go-version: ${{ env.GO_VERSION }}
          check-latest: false
          cache: true

      - name: the headers the toolkit needs
        # The same reason as in the staticcheck job above: anything that
        # analyses the whole tree on Linux compiles GLFW through C, and no
        # runner carries its headers.
        run: |
          set -euo pipefail
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends             libgl1-mesa-dev             libwayland-dev             libx11-dev             libxkbcommon-dev             xorg-dev
        shell: bash

      - name: the configuration is valid
        # Run separately and first, because a plain run ACCEPTS a configuration
        # this refuses. A key that does not exist, or a value outside what the
        # schema allows, is otherwise ignored in silence - and a linter reading
        # a setting nobody applied is a gate that reports what it feels like.
        run: go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.15.0 config verify

      - name: golangci-lint
        # Run rather than imported, so it never enters go.mod and the
        # dependency gate above does not see it - the same arrangement as
        # staticcheck, measured there on 2026-08-02.
        #
        # The version is pinned because an unpinned analyser turns somebody
        # else's release into a red build on a commit that changed nothing.
        #
        # Which linters run, and the measurement behind each, is in
        # .golangci.yml. Measured before switching this on: zero findings from
        # ineffassign and one from misspell, which turned out to be a comment
        # written in the wrong language rather than a typo.
        run: go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.15.0 run --build-tags "$(cat .github/build-tags)" ./...

  semgrep:
    name: semgrep
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
        with:
          python-version: "3.14"

      - name: the scanner, pinned
        # Pinned for the reason staticcheck and golangci-lint are pinned: an
        # unpinned analyser turns somebody else's release into a red build on a
        # commit that changed nothing.
        #
        # The version lives in .github/requirements-semgrep.txt rather than on
        # this line, and the reason is in that file: a version written into a
        # workflow step is watched by nothing, which is how staticcheck came to
        # be two releases behind a compiler it could not read. A requirements
        # file is an ecosystem Dependabot reads, so this one now arrives as a
        # pull request when it moves.
        #
        # The licence note and the reason for pinning moved there with it.
        run: pip install -r .github/requirements-semgrep.txt

      - name: scan
        # No account and no token. p/default is fetched anonymously from the
        # registry, used here, and never carried in this repository, because the
        # Semgrep Rules License allows the first and forbids the second.
        #
        # No --error and no --severity: the scan reports and the gate decides.
        # --severity knows INFO, WARNING and ERROR only, while registry rules
        # also carry HIGH and CRITICAL, so a gate built on that flag would
        # ignore exactly the severities it was asked to block.
        #
        # Metrics are off. This repository does not send telemetry about its own
        # source anywhere, which is the same promise the tool itself makes.
        #
        # One rule is excluded, and the reason is measured rather than assumed.
        # missing-integrity asks for a subresource integrity attribute, which
        # applies to a script or a stylesheet fetched from another origin. On
        # every page of web/public it matches lines 8 to 11 - the canonical link
        # and three hreflang alternates - while the one real stylesheet, at line
        # 31, it does not match at all. 48 findings, none of them about a
        # subresource. This site loads nothing from another origin by design.
        #
        # Excluded here rather than through a .semgrepignore file, and that is
        # also from measurement: a .semgrepignore REPLACES semgrep own default
        # patterns instead of adding to them. Measured 2026-08-27, adding one
        # took the scan from 217 files to 366 by pulling in all 166 guard test
        # files, and with them a new blocking finding. Security scanning of test
        # files is a question this project already answered for gosec, and the
        # answer was no.
        run: |
          semgrep scan --config p/default --metrics=off --oss-only --json --output semgrep.json --quiet --exclude-rule html.security.audit.missing-integrity.missing-integrity

      - name: decide
        # Separate from the scan on purpose. Measured on the development machine
        # 2026-08-27: a semgrep whose core failed printed four errors, exited 0,
        # and wrote a 23 byte file that was not JSON. Reading the exit code would
        # have called that a clean tree. The gate reads the report.
        run: python .github/scripts/semgrep_gate.py semgrep.json

  sbom:
    name: bill of materials
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e  # v7.0.0
        with:
          go-version: ${{ env.GO_VERSION }}

      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
        with:
          python-version: "3.14"

      - name: graphics and windowing headers
        # The window links OpenGL through C, so without these the toolkit does
        # not compile at all - and a scan of a binary that was never built is a
        # scan of nothing. Taken from the toolkit's own CI, the same list the
        # release workflow uses.
        run: |
          set -euo pipefail
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends \
            libgl1-mesa-dev \
            libwayland-dev \
            libx11-dev \
            libxkbcommon-dev \
            xorg-dev

      - name: build what a release would publish
        # Both binaries, because they do not carry the same code: the command
        # line links two modules and the window twenty-eight plus the fonts and
        # drawings they bring. Scanning one of them would ask half the question.
        run: |
          set -euo pipefail
          mkdir -p dist
          CGO_ENABLED=0 go build -tags "$(cat .github/build-tags)" -trimpath -o dist/tfg ./cmd/tfg
          CGO_ENABLED=1 go build -tags "$(cat .github/build-tags)" -trimpath -o dist/tfg-gui ./cmd/tfg-gui
          ls -l dist

      - name: the document we would publish
        # Generated from internal/legal, the reviewed list of what we ship, with
        # versions read from the build. Not from a scan: measured 2026-08-27,
        # syft reading the window binary names every module with an exact
        # version and attaches a licence to one of thirty.
        run: go run -tags "$(cat .github/build-tags)" ./internal/legal/cmd/sbom -seed "${GITHUB_SHA}" -o ours.spdx.json

      - name: scan the binaries
        # Pinned by commit like every other action here. The scan is evidence,
        # not the document: its job is to ask whether the built binaries contain
        # something the registry does not know about.
        uses: anchore/sbom-action@66cbf4bc1f1c0d2edc94016e65bc221b6bb0ad6c  # v0.24.3
        with:
          path: dist
          format: syft-json
          output-file: scan.json
          upload-artifact: false
          upload-release-assets: false

      - name: the registry has to account for everything the scan found
        # Separate from the scan for the reason the semgrep gate is separate: a
        # scanner that falls over can still exit zero, and a gate reading the
        # exit code would call that a clean tree. This one reads the report, and
        # refuses when the report is unusable rather than treating it as empty.
        run: python .github/scripts/sbom_gate.py scan.json ours.spdx.json

  touched:
    name: what this push touched
    runs-on: ubuntu-latest
    timeout-minutes: 5
    outputs:
      concurrency: ${{ steps.look.outputs.concurrency }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false
          # The comparison needs the earlier commit, and the default checkout
          # fetches one.
          fetch-depth: 0

      - name: did anything concurrent change
        id: look
        # The three files concurrency is allowed to live in are not a guess.
        # They are the map in internal/guard/concurrency_test.go.
        #
        # This used to say the map guard was enough to keep the two in step: "a
        # fourth file growing a goroutine turns that guard red before it gets
        # here, so this list cannot quietly fall behind the tree". That was not
        # true, and adding the fourth file on 2026-09-05 is what showed it. The
        # map guard is red only while the new file is NOT in the map. The moment
        # somebody adds it there - which is what the guard's own message tells
        # them to do - it goes green, and nothing at all asks whether this line
        # was updated too. The list could then fall behind exactly when it
        # mattered: concurrency living in a file the detector is not run for.
        #
        # TestTheRaceDetectorIsRunForEveryFileThatDeclaresConcurrency now reads
        # this line and compares it against the map, so the two cannot drift.
        #
        # go.mod is watched as well. A toolchain or dependency change can alter
        # what the detector sees even when none of our own lines moved.
        #
        # So is this file, since 2026-09-24 and the owner's decision. A change
        # to the race job itself used to leave it skipped, so the first run of
        # a new definition was the weekly sweep, days after it merged. And so
        # is .github/build-tags, which every command of the job reads and which
        # decides the files it compiles - the same reason as go.mod, named by
        # an outside review of the pull request that split the job. And so are
        # the weights and the script that lay its parts out (O298), since a
        # change to either decides which guards each part runs.
        #
        # Anything unclear counts as touched. A first push, a branch with no
        # comparable parent, a pull request event with no before - all answer
        # true, because the cost of running the detector when it was not needed
        # is ten minutes and the cost of skipping it when it was is a data race
        # in somebody else's file.
        run: |
          set -euo pipefail
          watched='internal/format/registry.go internal/damage/damage.go cmd/tfg/main.go internal/gui/window/run.go internal/gui/run_cgo.go internal/gui/window/tidy.go internal/audit/parallel.go internal/engine/parallel.go internal/tool/tool.go internal/gui/window/tools.go internal/gui/window/work.go internal/gui/window/closing.go internal/gui/window/dropping.go internal/format/video/ahead.go go.mod .github/workflows/ci.yml .github/build-tags .github/race-weights .github/scripts/race_parts.py'
          # On a pull request there is no "before" - the field belongs to a push
          # - so this asked for something empty and every pull request answered
          # "touched". That quietly undid the decision of 2026-08-20, because
          # from the day this project started taking pull requests the detector
          # was back to running on everything. The base of the pull request is
          # the commit to compare against, and github.sha is the merge commit,
          # so the difference between them is exactly what the pull request
          # changes.
          before="${{ github.event.pull_request.base.sha || github.event.before }}"
          if [ -z "$before" ] \
            || [ "$before" = "0000000000000000000000000000000000000000" ] \
            || ! git cat-file -e "${before}^{commit}" 2>/dev/null
          then
            echo "no earlier commit to compare against, so this counts as touched"
            echo "concurrency=true" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          changed="$(git diff --name-only "$before" "${{ github.sha }}")"
          echo "changed in this push:"
          echo "$changed"

          hit=false
          for f in $watched; do
            if printf '%s\n' "$changed" | grep -qx "$f"; then
              echo "  -> $f is one of the files the race detector is for"
              hit=true
            fi
          done
          echo "concurrency=$hit" >> "$GITHUB_OUTPUT"
        shell: bash

  race:
    name: race detector (part ${{ strategy.job-index }} of ${{ strategy.job-total }})
    needs: touched
    # Not on every push, decided on 2026-08-20 after the owner asked what it was
    # costing. Measured that day: 10m31s on the runner, against about a minute
    # for the whole matrix - so it was the longest thing in the run by a factor
    # of ten, on every push, including the ones that only touched a document.
    #
    # What makes that safe to change rather than a corner cut: concurrency in
    # this tree is confined to the files declared in
    # internal/guard/concurrency_test.go, by a guard that fails if another one
    # grows a goroutine. A push that does not touch them cannot introduce a race
    # for this to find, so running it there bought nothing.
    #
    # Three ways in now. A push that touches one of those files or this
    # workflow, the weekly sweep that fuzzing already uses, and by hand. The
    # weekly run is what catches a race that arrives through a dependency
    # rather than through us.
    if: >-
      github.event_name == 'schedule' ||
      github.event_name == 'workflow_dispatch' ||
      needs.touched.outputs.concurrency == 'true'
    runs-on: ubuntu-latest
    # Five parts, the owner's decision. In one process the whole package under
    # the detector took 32 to 42 minutes, and six of the twelve runs on
    # 2026-09-23 and 2026-09-24 were killed at the ceiling with no data race in
    # their logs. Both ceilings had been raised once already, on 2026-08-31 -
    # the job's from 30 to 45 minutes and Go's from 25 to 40 - for the same
    # reason, and a problem that keeps coming back is the wrong shape rather
    # than a missing notch. Four parts weighed 1074 s each by the weights of
    # 2026-11-12, past 85% of their twenty minutes, and two of them took 1055
    # and 1067 s that day. The guards run one after another - none calls
    # t.Parallel - so the processes share the time between them, and every
    # test still runs under the detector once, in one of them.
    #
    # Every part reports. One red part does not cancel the others, whose tests
    # would then go unrun.
    #
    # The ceiling is the sum of the limits inside it, with room left over, so
    # that each of them fires first and names what was slow: about four minutes
    # to set up and compile (the compile alone took 3m03s on the first run),
    # twenty for the guards, five for the other packages. The guards are laid
    # out by what each weighs (.github/race-weights), because a split by name
    # gave parts of 1250, 1158, 795 and 526 s on the slowest processor
    # measured, two of them at the twenty minutes (O298).
    strategy:
      fail-fast: false
      matrix:
        part: [0, 1, 2, 3, 4]
    timeout-minutes: 35
    env:
      # The one thing in this project that needs a C toolchain. Linux runners
      # ship one, so this job carries the cost and the matrix above stays on
      # CGO_ENABLED=0 and stays fast.
      CGO_ENABLED: "1"
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e  # v7.0.0
        with:
          go-version: ${{ env.GO_VERSION }}
          check-latest: false
          cache: true

      - name: the headers the toolkit needs
        # The window reaches OpenGL through C, so anything that builds or
        # analyses the whole tree on Linux compiles GLFW - and no runner carries
        # its headers. Measured on 2026-08-20, the first run after the
        # repository went public and so the first one this job has ever had
        # against the toolkit: "wayland-client-core.h: No such file or
        # directory", and the job never reached our code at all.
        #
        # Taken from the toolkit's own CI rather than from a remembered list.
        run: |
          set -euo pipefail
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends             libgl1-mesa-dev             libwayland-dev             libx11-dev             libxkbcommon-dev             xorg-dev
        shell: bash

      - name: the machine this part runs on
        # O298, 2026-11-03. Part 2 ran past its twenty minutes in one run of
        # three since 2026-10-26, main included, and the log named the runner's
        # image and region and nothing about the machine. With this step the
        # answer was the processor: the same part took 1202 s on an AMD EPYC
        # 7763 and 689 s on an EPYC 9V45, every test of it slower by the same
        # factor, while part 3 took 525 and 530 s on two 7763s. The weights
        # the parts are laid out by come from these numbers, so this stays to
        # say which processor a slow part had when the weights stop fitting.
        run: |
          set -euo pipefail
          echo "processors: $(nproc)"
          lscpu | grep -E '^(Model name|Thread\(s\) per core|Core\(s\) per socket|Socket\(s\)|CPU max MHz|L3 cache|Hypervisor vendor|Virtualization type):' || true
          free -m
          echo "load average: $(cat /proc/loadavg)"
        shell: bash

      - name: test this part under the race detector
        # A data race is the one defect class here that nothing else notices. It
        # does not change a size, and on the run that happens to interleave the
        # safe way it does not change a byte either - so determinism and the
        # pinned values both stay green while the file is wrong once a month on
        # somebody else's machine. The guard that keeps concurrency confined to
        # the declared files lives in internal/guard, so this and that one
        # answer different halves of the same worry.
        #
        # Which tests are this part's is worked out here, from the test binary,
        # rather than written down. A list kept by hand would miss the next
        # guard somebody adds, and miss it green. The list is asked with -race,
        # because a file in the package builds only without it, and it keeps
        # Fuzz and Example because go test runs those as tests too.
        #
        # The tests .github/race-weights names are laid out by weight, the
        # heaviest first, each into the part that is lightest so far. Every
        # other test goes by the checksum of its name, so adding or removing a
        # light test moves no other test. It was every fourth name of a sorted
        # list at first, and one guard added on this job's own pull request
        # moved every name after it. Then the checksum alone, which is even only
        # on average, and with three guards of 330 to 350 s it was not. A test
        # missing from the weights that takes a minute or more fails the part
        # with the line to add, and a weight for a test that is gone fails
        # every part, so the list cannot fall behind the tests quietly.
        #
        # Three things fail the part rather than let it pass on nothing -
        # go test with a -run pattern that matches no test exits 0. An index the
        # matrix does not agree with (the documentation does not say that
        # job-index counts from nought, so this asks), a part given no test,
        # and a part that never started a test it was given. That last one
        # compares names rather than counts, so a stray line that looks like
        # a start cannot stand in for a test that did not run.
        #
        # The timeout is stated rather than left to Go's ten minutes a package,
        # and stays below the job's ceiling, so a slow part fails as a test with
        # a name rather than as a killed job with no output. Go's ten minutes
        # killed this job on 2026-08-25, before a timeout was stated here.
        # By the weights the heaviest part is 861 s on the slowest processor
        # measured, and twenty minutes is 1.39 times that.
        #
        # The processor's counters and the clock are read just before the
        # tests, for the step after this one (O298).
        env:
          PART: ${{ strategy.job-index }}
          PARTS: ${{ strategy.job-total }}
          LISTED: ${{ matrix.part }}
        run: |
          set -euo pipefail
          if [ "$PART" != "$LISTED" ] || [ "$PART" -ge "$PARTS" ]; then
            echo "job $PART of $PARTS is part $LISTED in the matrix, and the split needs the two equal and below the total."
            echo "List strategy.matrix.part as 0, 1, 2 and on, in order, and check the context names in this step's env."
            exit 1
          fi
          go test -tags "$(cat .github/build-tags)" ./internal/guard/ -race -list '.*' > listed.txt || { cat listed.txt; exit 1; }
          grep -E '^(Test|Fuzz|Example)' listed.txt > names.txt || { echo "the test binary listed no Test, Fuzz or Example function. What it printed:"; cat listed.txt; exit 1; }
          python3 .github/scripts/race_parts.py split names.txt .github/race-weights "$PART" "$PARTS" > mine.txt
          planned=$(wc -l < mine.txt)
          echo "part $PART of $PARTS runs $planned of $(wc -l < names.txt) tests"
          if [ "$planned" -eq 0 ]; then
            echo "part $PART of $PARTS was given no test - the checksum of no listed name lands here."
            echo "With this few tests, use fewer parts in strategy.matrix.part."
            exit 1
          fi
          head -n 1 /proc/stat > stat-before.txt
          date +%s > time-before.txt
          go test -tags "$(cat .github/build-tags)" ./internal/guard/ -count=1 -race -timeout 20m -v -run "^($(paste -sd'|' mine.txt))\$" 2>&1 | tee part.log
          missing=$(comm -23 <(sort mine.txt) <(sed -n 's/^=== RUN   \([^/]*\)$/\1/p' part.log | sort -u))
          if [ -n "$missing" ]; then
            echo "part $PART was given $planned tests and never ran these:"
            echo "$missing"
            echo "Each of these is a name the -run pattern did not reach, or a test the binary skipped before it started."
            exit 1
          fi
          python3 .github/scripts/race_parts.py unlisted .github/race-weights part.log
        shell: bash

      - name: what the processor did while this part ran
        # The other half of the step that says what the machine is (O298). The
        # counters are the whole machine's, read just before the tests and
        # again now. iowait is time the processors sat idle while disk I/O was
        # pending, not time a test spent waiting for it, and the kernel calls
        # the counter unreliable. steal depends on the platform: Microsoft
        # documents it as not applicable to Azure, so nought there proves
        # nothing about the host. The processes are ranked by the processor
        # time each has used since it started, which ELAPSED dates, so one the
        # part left running stands out from the runner's own. Runs after red
        # tests as well, because a slow part is a red one.
        if: ${{ !cancelled() }}
        run: |
          set -euo pipefail
          if [ ! -s stat-before.txt ]; then
            echo "the tests of this part never started, so there is nothing to compare"
            exit 0
          fi
          read -r _ user0 nice0 system0 idle0 iowait0 irq0 softirq0 steal0 _ < stat-before.txt
          read -r _ user1 nice1 system1 idle1 iowait1 irq1 softirq1 steal1 _ < <(head -n 1 /proc/stat)
          busy=$(( (user1 + nice1 + system1 + irq1 + softirq1) - (user0 + nice0 + system0 + irq0 + softirq0) ))
          idle=$(( idle1 - idle0 ))
          iowait=$(( iowait1 - iowait0 ))
          steal=$(( steal1 - steal0 ))
          total=$(( busy + idle + iowait + steal ))
          echo "over $(( $(date +%s) - $(cat time-before.txt) )) s on $(nproc) processors:"
          if [ "$total" -gt 0 ]; then
            echo "  busy $(( 100 * busy / total ))%, idle $(( 100 * idle / total ))%, idle with disk I/O pending (iowait) $(( 100 * iowait / total ))%, steal (platform dependent) $(( 100 * steal / total ))%"
          fi
          echo "load average: $(cat /proc/loadavg)"
          echo "the processes still running now, by processor time used since each started (ELAPSED):"
          ps -eo pid,ppid,etime,time,pcpu,comm --sort=-time > processes.txt
          head -n 12 processes.txt
        shell: bash

      - name: the other packages under the race detector
        # Every package outside internal/guard, in part 0 alone. None holds a
        # test today - the first run took one second for all of them - and one
        # written there has to reach the detector as well.
        #
        # A step of its own with a ceiling of its own, rather than a second
        # command after the guards. Go's -timeout holds one test binary, so two
        # commands in one step add up under nothing but the job's ceiling, and
        # the job would be killed past it with no name in the log - an outside
        # review of the pull request that split the job. Runs after red guards
        # as well, so its answer is not lost with theirs.
        if: ${{ !cancelled() && matrix.part == 0 }}
        timeout-minutes: 5
        run: |
          set -euo pipefail
          go list -tags "$(cat .github/build-tags)" ./... | grep -v '/internal/guard$' > others.txt
          mapfile -t others < others.txt
          go test -tags "$(cat .github/build-tags)" -count=1 -race -timeout 4m "${others[@]}"
        shell: bash

  coverage:
    name: coverage gate
    runs-on: ubuntu-latest
    timeout-minutes: 20
    env:
      CGO_ENABLED: "0"
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e  # v7.0.0
        with:
          go-version: ${{ env.GO_VERSION }}
          check-latest: false
          # Keyed on go.sum. The one dependency is the YAML parser behind the
          # recipe - see docs/STACK.md.
          cache: true

      - name: measure
        # -coverpkg is not optional here. The guard tests live in their own
        # package, and by default Go credits coverage only to the package
        # under test - which reports 0.0% and makes the gate meaningless.
        # Measured, not assumed.
        #
        # The timeout is stated rather than left to Go, since 2026-09-03, and
        # for the same reason the race job above states its own. Go allows ten
        # minutes PER PACKAGE by default while this job allows twenty for all of
        # it, so internal/guard died on a limit nobody had chosen - a stack
        # trace out of whichever test was running when the alarm went off,
        # instead of a failure naming something.
        #
        # Measured on the runner rather than guessed. This step took 375 s and
        # 457 s on two consecutive main runs of 2026-09-02 and 2026-09-03, which
        # is 22 percent of variance on code that barely moved between them, and
        # the default cuts in at 600 s. A branch adding eight seconds of
        # coverage instrumented work then timed out. Eight seconds is not what
        # went wrong: 457 against 600 was never a margin, and a limit that
        # decides on how busy the runner is tells you nothing about the code.
        #
        # Atomic counters are the cost. Every statement in every internal
        # package pays one, and this package renders twenty five screens and
        # generates files for twenty four formats. Eighteen minutes sits under
        # the job's own ceiling on purpose, so a genuinely stuck run still fails
        # as a test with output rather than as a killed job without any.
        run: >
          go test -tags "$(cat .github/build-tags)" ./... -count=1 -covermode=atomic
          -coverpkg=./internal/...,./cmd/...
          -coverprofile=coverage.out -timeout 18m

      - name: gate
        # The threshold lives in exactly one place, .github/coverage-threshold.
        # It rises with coverage and is never lowered to turn a red run green.
        # Lowering it is a decision for the owner, not a way to get unblocked.
        run: |
          set -euo pipefail
          threshold=$(tr -d '[:space:]' < .github/coverage-threshold)
          actual=$(go tool cover -func=coverage.out | awk '/^total:/ {gsub("%","",$3); print $3}')
          echo "coverage ${actual}% - threshold ${threshold}%"
          awk -v a="$actual" -v t="$threshold" 'BEGIN { exit (a+0 >= t+0) ? 0 : 1 }' \
            || { echo "coverage ${actual}% is below the threshold ${threshold}%"; exit 1; }
        shell: bash

  fidelity:
    name: reference tools actually installed
    # The oracle guards skip when the tool they need is missing, loudly, and a
    # skip is not a check. The matrix runners have python and node and nothing
    # else, so on an ordinary push most of those guards report a skip and the
    # run is green having verified almost nothing about the files themselves.
    #
    # This job installs Inkscape, 7z, ffmpeg and poppler so the same guards run
    # for real. It is separate from the matrix because installing a graphics
    # stack takes minutes and a push should not wait for it.
    #
    # What it does NOT do, said plainly: it does not walk many sizes. The
    # guards it runs check the realistic size and the smallest ones, which is
    # where the one defect this ever found was hiding - an SVG that rendered to
    # a blank canvas at exactly its minimum, 2026-08-03. The wider sweep across
    # sizes, seeds and label settings lives in tools/probes/fidelity-sweep.py
    # and is run by hand, because tools/ is outside the repository. See O51.
    runs-on: ubuntu-latest
    timeout-minutes: 30
    env:
      CGO_ENABLED: "0"
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e  # v7.0.0
        with:
          go-version: ${{ env.GO_VERSION }}
          check-latest: false
          cache: true

      - name: the reference tools
        run: |
          set -euo pipefail
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends \
            p7zip-full ffmpeg poppler-utils inkscape python3-pil python3-yaml gdal-bin pandoc

          # RTF is read by pandoc, the one of five readers measured that is
          # an apt install here (docs/RTF-2026-10-15.md section 6.1). Its
          # readings of good files - wrong letters in codepage, a dropped
          # character after every letter written literal, hidden text left
          # out - are held by the RTF guard as what the settings tell a user,
          # and 3.1.3 and 3.7.0.2 read every file of that measurement alike.
          # Asked for its version, so a pandoc that did not install stops this
          # step rather than turning the RTF guard into a skip. Without a pipe:
          # under pipefail a reader that stops early can fail a good install.
          pandoc --version

          # GeoJSON is read by GDAL and its shapes judged by shapely, which is
          # GEOS underneath (docs/GEOJSON-2026-10-07.md). shapely goes in for
          # the same interpreter the oracle reaches for, as Pillow does below.
          # Both are asked for their version, so a tool that did not install
          # stops this step rather than turning the GeoJSON guards into skips.
          python -m pip install --break-system-packages shapely
          ogrinfo --version
          python -c "import shapely; print('shapely', shapely.__version__, 'GEOS', shapely.geos_version_string)"

          # Mail is read by mailparser beside Python's email package - the
          # parser much of the mail handling written in Node uses, and the one
          # that refuses a message of more than 1000 MIME entities
          # (docs/EML-2026-10-07.md section 5.1). Pinned, installed outside the
          # checkout, and named to the guard through TFG_MAILPARSER. Asked for
          # its version, so a package that did not install stops this step, and
          # the guard fails if it is named and reads nothing.
          #
          # Without a committed lockfile, on purpose for now: one in the
          # repository puts the whole tree into the dependency graph, and the
          # licence gate then blocks two packages of it (review of #173,
          # docs/REVIEW-173-2026-10-07.md). Whether CI-only tools belong under
          # that gate is the owner's decision, not a fix.
          npm install --prefix "$RUNNER_TEMP/mailparser" mailparser@3.10.0
          echo "TFG_MAILPARSER=$RUNNER_TEMP/mailparser/node_modules/mailparser" >> "$GITHUB_ENV"
          node -e "console.log('mailparser', require(process.argv[1] + '/package.json').version)" "$RUNNER_TEMP/mailparser/node_modules/mailparser"

          # OTLP is read by the OpenTelemetry Collector, which is asked to
          # write every batch back byte for byte (docs/OTLP-2026-11-10.md
          # section 5). The contrib distribution is the one that carries the
          # file receiver and the file exporter. Its binary is taken out of
          # the image the project publishes, pinned by version and by digest,
          # put outside the checkout and named to the guard through
          # TFG_OTELCOL. Asked for its version, so an image that did not
          # arrive stops this step rather than turning the OTLP guard into a
          # skip.
          otelcol='otel/opentelemetry-collector-contrib:0.165.0@sha256:e40d61f10c9a617cca1ffd1be4d7e2b3a4b0f0001798ff07e58cabe82e618cea'
          mkdir -p "$RUNNER_TEMP/otelcol"
          docker create --name tfg-otelcol "$otelcol"
          docker cp tfg-otelcol:/otelcol-contrib "$RUNNER_TEMP/otelcol/otelcol-contrib"
          docker rm tfg-otelcol
          echo "TFG_OTELCOL=$RUNNER_TEMP/otelcol/otelcol-contrib" >> "$GITHUB_ENV"
          "$RUNNER_TEMP/otelcol/otelcol-contrib" --version

          # The distribution's Pillow cannot open an AVIF - measured on this
          # runner, PIL.UnidentifiedImageError on a file the structural checker
          # had just called sound. Installed for the SAME interpreter the oracle
          # reaches for, then asked whether it can actually read one. No version
          # is named: the question is what this Pillow can do, not when the
          # support landed.
          python -m pip install --break-system-packages --upgrade pillow
          python - <<'PY'
          from PIL import Image, features
          print("pillow", Image.__version__, "avif:", features.check("avif"))
          if not features.check("avif"):
              raise SystemExit("this Pillow cannot read AVIF, so the oracle would fail on a good file")
          PY
        shell: bash

      - name: every format past its reference tool
        # -v so that a skip is visible in the log. A tool that failed to install
        # would otherwise turn this job back into the green nothing it exists
        # to replace.
        run: go test -tags "$(cat .github/build-tags)" ./internal/guard/ -count=1 -run 'ReferenceTool' -v
        shell: bash

  npm:
    name: npm package on ${{ matrix.os }}
    # The npm package (npm/testing-files-generator) runs tfg and reads what it
    # writes from JavaScript, so nothing in the Go suite runs it. Its own tests
    # run here against the binary this commit builds, on the three systems a
    # release has binaries for - Windows above all, because the rename that
    # settles a race between test workers is refused there in ways it is not
    # elsewhere. Node 22 is the oldest the package declares and Playwright
    # supports, so it is the one tested.
    #
    # The Playwright example runs on Linux only. It is the package's acceptance
    # test: an upload form with four mistakes, where the generated set has to
    # find all four, the tests written with Buffer.alloc have to find none, and
    # with the mistakes fixed nothing may fail - that last run is the control
    # without which a red test could come from the tests. One browser on one
    # system is enough to show that, and the package itself is tested on all
    # three. docs/PLAYWRIGHT-2026-11-04.md.
    timeout-minutes: 20
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    env:
      CGO_ENABLED: "0"
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e  # v7.0.0
        with:
          go-version: ${{ env.GO_VERSION }}
          check-latest: false
          cache: true

      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
        with:
          node-version: "22"

      - name: build tfg where the package's tests and the example look for it
        run: go build -tags "$(cat .github/build-tags)" -o "tfg$(go env GOEXE)" ./cmd/tfg
        shell: bash

      - name: the package's own tests
        working-directory: npm/testing-files-generator
        run: node --test "test/*.test.js"
        shell: bash

      - name: the Playwright example finds the four mistakes, and nothing once they are fixed
        if: runner.os == 'Linux'
        working-directory: examples/playwright
        run: |
          set -euo pipefail
          npm ci --no-audit --no-fund
          npx playwright install --with-deps chromium
          npx tsc --noEmit
          node check.mjs
        shell: bash

  python:
    name: Python package on ${{ matrix.os }} with Python ${{ matrix.python }}
    # The Python package (python/testing-files-generator) runs tfg and reads
    # what it writes, so nothing in the Go suite runs it. Its own tests run
    # here against the binary this commit builds, on the three systems a
    # release has binaries for - Windows above all, because the rename that
    # settles a race between test workers is refused there in ways it is not
    # elsewhere. Python 3.10 is the oldest the package declares, and the
    # newest is tried beside it on Linux. The tests of the release tools are
    # among them: the wheels are laid out from archives the tests make.
    # docs/PYTEST-2026-11-09.md.
    timeout-minutes: 20
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: ubuntu-latest
            python: "3.10"
          - os: ubuntu-latest
            python: "3.14"
          - os: windows-latest
            python: "3.10"
          - os: macos-latest
            python: "3.10"
    runs-on: ${{ matrix.os }}
    env:
      CGO_ENABLED: "0"
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e  # v7.0.0
        with:
          go-version: ${{ env.GO_VERSION }}
          check-latest: false
          cache: true

      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
        with:
          python-version: ${{ matrix.python }}

      - name: build tfg where the package's tests look for it
        run: go build -tags "$(cat .github/build-tags)" -o "tfg$(go env GOEXE)" ./cmd/tfg
        shell: bash

      - name: the package's own tests
        working-directory: python/testing-files-generator
        run: |
          python -m pip install --disable-pip-version-check -r ../../.github/requirements-pypi.txt
          python -m pytest -p no:cacheprovider
        shell: bash

  fuzz:
    name: fuzzing with a time budget
    # Weekly and by hand, never on a push. Fuzzing searches without end, so a
    # budget picked to fit a commit gate would be a gate that says "fuzzing
    # passed" after twenty seconds of looking - which is worth less than not
    # claiming it. See docs/OBSERVATIONS.md, O34.
    #
    # What the push jobs do run is the seed corpus in testdata/fuzz, because
    # go test executes fuzz targets as ordinary tests. That is regression
    # cover for what has already been found, and it is not the same thing as
    # searching.
    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    # Seven targets at five minutes each, plus the build and the baseline pass.
    timeout-minutes: 55
    env:
      CGO_ENABLED: "0"
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e  # v7.0.0
        with:
          go-version: ${{ env.GO_VERSION }}
          check-latest: false
          cache: true

      - name: search
        # One target at a time, because -fuzz takes exactly one. Five minutes
        # each - long enough to be a search rather than a gesture, short enough
        # that a weekly run stays cheap.
        #
        # A finding here is not fixed by this job. It has to be pulled into
        # testdata/fuzz and committed, or it disappears with the runner and the
        # next search starts from nothing.
        run: |
          set -euo pipefail
          for target in FuzzParseSize FuzzParseRecipe FuzzNameTemplate FuzzCanonicalRecipe FuzzPresetExpansion FuzzChecksumFile FuzzArchiveScan; do
            echo "=== $target ==="
            go test -tags "$(cat .github/build-tags)" ./internal/guard/ -run "^$" -fuzz "^${target}$" -fuzztime 5m
          done
        shell: bash

      - name: keep what was found
        # The corpus a failing run leaves behind is the whole value of the run,
        # and it lives in the runner's cache directory rather than the tree.
        if: failure()
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
        with:
          name: fuzz-findings
          path: |
            internal/guard/testdata/fuzz/**
            ~/.cache/go-build/fuzz/**
          if-no-files-found: warn