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.0"

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.
        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 [ "$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

  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.8.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.1 -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.13.2 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.13.2 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@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.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@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.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@3ad7283483fc7af8ff2b4ea19663c2d5ca935e26  # v0.24.0
        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.
        #
        # 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 go.mod .github/workflows/ci.yml .github/build-tags'
          # 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
    # Four parts since 2026-09-24, the owner's decision. 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. The guards run one after another - none calls
    # t.Parallel - so four 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. Measured on the first
    # run, split by a sorted list: 677, 635, 164 and 154 s of guards in the
    # four parts, 14m55s for the longest part. The two slowest guards take 329
    # and 222 s, and wherever they land together, that part is the slow one.
    strategy:
      fail-fast: false
      matrix:
        part: [0, 1, 2, 3]
    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: 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.
        #
        # A test's part is the checksum of its name (cksum) modulo the number
        # of parts, so adding or removing a 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 - the part
        # holding the slowest guards changed from one commit to the next. The
        # parts are even only on average, and which one is slow now changes only
        # with what is in it.
        #
        # 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.
        # Twenty minutes is 1.8 times the slowest part measured.
        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; }
          while IFS= read -r name; do
            read -r sum _ < <(printf '%s' "$name" | cksum)
            if [ $((sum % PARTS)) -eq "$PART" ]; then
              echo "$name"
            fi
          done < names.txt > 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
          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
        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

          # 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

  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
    # Four targets at five minutes each, plus the build and the baseline pass.
    timeout-minutes: 45
    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; 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@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
        with:
          name: fuzz-findings
          path: |
            internal/guard/testdata/fuzz/**
            ~/.cache/go-build/fuzz/**
          if-no-files-found: warn