Skip to content
PREFLIGHT 0.9.0
Menu

Local checks#

How maintainers build, test and release this project with Docker, and the Composer scripts behind the gate. The pre-flight checklist, run from your own desk: run the same gate CI runs before you push anything.

The full gate#

Run the template lint and the fixture tests with Docker:

linux

docker run --rm -v "$(pwd):/app" -v stack-composer-cache:/tmp/cache -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 composer install
docker run --rm -v "$(pwd):/app" -v stack-composer-cache:/tmp/cache -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 composer ci

windows

docker run --rm -v "${PWD}:/app" -v stack-composer-cache:/tmp/cache -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 composer install
docker run --rm -v "${PWD}:/app" -v stack-composer-cache:/tmp/cache -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 composer ci

The stack-composer-cache volume keeps Composer's downloads between runs; Docker creates it the first time.

In PowerShell, use ${PWD} instead of $(pwd). composer ci is the whole gate: it runs the template lint, the fixture tests, Pint, PHPStan, the unit tests, the agent-ready file check and the docs site check, in that order.

Composer scripts#

The scripts from composer.json:

{
    "ci": [
        "php bin/lint-templates",
        "php bin/lint-templates --test",
        "@lint",
        "@analyse",
        "@test",
        "@site:agent-ready-check",
        "@docs:check"
    ],
    "lint": "pint --test",
    "fix": "pint",
    "analyse": "phpstan analyse --memory-limit=1G",
    "test": "phpunit",
    "contract:update": "php bin/contract-update.php",
    "site:agent-ready": "php bin/agent-ready.php",
    "site:agent-ready-check": "php bin/agent-ready.php --check",
    "docs": "php bin/docs-site.php",
    "docs:check": "php bin/docs-site.php --check"
}
Script Runs What it does
ci the array above The full CI gate: template lint, fixture tests, Pint, PHPStan, unit tests, agent-ready files, docs site.
lint pint --test Run Pint in test mode; fails on style errors without changing files.
fix pint Run Pint and rewrite the files it finds.
analyse phpstan analyse --memory-limit=1G Run PHPStan with a 1G memory limit.
test phpunit Run the PHPUnit suite: the inputs contract test (tests/ComponentsContractTest.php), the docs input-table test (tests/DocsInputTablesTest.php), which fails when an input table in the README, the components reference or a component guide disagrees with contract/inputs.json, the egress test (tests/DocsEgressTest.php), which fails when Which hosts the jobs reach misses a component, a fetched host or an image registry, the template jobs test (tests/TemplateJobsTest.php), which fails when a job loses interruptible: true or a timeout of an hour or less, or a template gains a credential, and the front page pins test (tests/FrontPagePinsTest.php), which fails when site/index.html pins a commit or tag other than the newest release the README pins, or a placard or the README art names another tag.
contract:update php bin/contract-update.php Rewrite contract/inputs.json from templates/. Run it only when the change is deliberate; a rename or a changed default is a breaking change that needs a new major version.
site:agent-ready php bin/agent-ready.php Rewrite the Markdown twins, llms.txt, llms-full.txt, robots.txt and sitemap.xml in site/ (Squire's agent-ready kit).
site:agent-ready-check php bin/agent-ready.php --check Fail when the agent-ready files are stale, a page lacks its Markdown link, a prompt drifts from the docs, or the kit was edited here.
docs php bin/docs-site.php Build the docs site from docs/ into site/docs/ (Squire's docs builder): render the pages, fill the generated command and environment reference, and stamp the current version.
docs:check php bin/docs-site.php --check Fail when the built docs site is stale or the generated command or environment reference has drifted from the CLI or source.

The PHP fixture app#

Run the PHP fixture app separately:

docker run --rm -v "$(pwd)/tests/fixture-app:/app" -v stack-composer-cache:/tmp/cache -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 composer install
docker run --rm -v "$(pwd)/tests/fixture-app:/app" -w /app php:8.4-cli-trixie vendor/bin/phpunit

The portability fixtures#

Run the portability fixtures with Docker. The check runs the component's own probe in the component's own Buildah image against tests/portability/app, once clean and once per flaw, and exits 0 only when the clean build passes every check and each flaw fails the check it targets. Two regression builds, one that reopens /proc/self/fd/2 and one that signals its process group on SIGTERM, must pass every check too. It takes about two minutes. --security-opt seccomp=unconfined lets Buildah open the user namespace that Docker's default seccomp profile refuses; it grants no capabilities and is not --privileged.

linux

docker run --rm --security-opt seccomp=unconfined -v "$(pwd):/src:ro" -w /src \
  quay.io/buildah/stable:v1.45.1-immutable@sha256:e5a33092657823b0830186ea525054cf4cdeef29b6a44833444c59d86f561f29 \
  sh tests/check-portability.sh

windows

pwsh -File tests/check-portability.ps1

To run some cases only, set PORTABILITY_CASES (for example -e PORTABILITY_CASES="none sigterm" on the docker run), or pass -Cases none,sigterm to the .ps1.

The accessibility gate#

The site's pages have an accessibility gate: the a11y component's own checker (templates/a11y/check.mjs, axe-core in Playwright), run in Docker with the image and versions pinned in templates/a11y/template.yml, so no host browser is needed and a local run checks the same way as the pipeline. With no options it checks the front page and every docs page at WCAG 2.2 AA, in light and dark mode at 320 px and 1280 px, with the reflow check, and fails on any violation:

linux

sh scripts/a11y.sh

windows

scripts\a11y.ps1

Options pick another folder, pages, tags, a running site or a folder for the reports: --site=DIR --pages='["index.html"]' --tags='["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"]' --base-url=URL --report=DIR (PowerShell: -Site, -Pages, -Tags, -BaseUrl, -Report). With --base-url=URL (or the A11Y_BASE_URL environment variable) the gate checks a running site at URL instead of a folder of HTML, as the component's base_url input does in CI; localhost inside the container is the container itself, so a site on the host is reached as host.docker.internal.

The accessibility fixtures#

tests/check-a11y.sh (and tests/check-a11y.ps1) prove the checker still tells a clean site from a bad one. They run the gate against tests/a11y-fixtures at the component's default WCAG 2.1 AA and exit 0 only when the good site passes, the bad site fails with each known flaw named (a missing lang, an image with no alt, an unlabeled input, weak contrast, a page that scrolls sideways at 320 px, and a palette that fails in dark mode only), a missing page fails with HTTP 404, and a glob that matches nothing stops with a configuration error. They need Docker; the contract job does not run them.

linux

sh tests/check-a11y.sh

windows

pwsh -File tests/check-a11y.ps1

tests/check-a11y-inline.sh (and .ps1) checks that the heredoc in the template is a byte-for-byte copy of templates/a11y/check.mjs; the contract job runs it. After editing check.mjs, run sh tests/check-a11y-inline.sh --write (PowerShell: tests\check-a11y-inline.ps1 -Write) to copy it into the template.

tests/check-a11y-runner.sh (and .ps1) keeps the local runner honest: scripts/a11y.sh and scripts/a11y.ps1 must still read the image and the axe versions from templates/a11y/template.yml, pass every A11Y_... variable to scripts/a11y-container.sh, keep their consumer options (--site, --pages, --tags, --report, --base-url), and hard-code no pin of their own. The contract job runs it.

The must-fail fixtures#

tests/check-php-test-fails.sh, tests/check-phpstan-fails.sh, tests/check-pint-fails.sh, tests/check-eslint-fails.sh, tests/check-secret-detection-fails.sh and tests/check-sbom-fails.sh (each with a .ps1 twin) prove the php-test, phpstan, pint, eslint, secret-detection and sbom components still fail a bad app and pass a clean one. Each asserts its template keeps the job lines it promises, then runs the component's own commands from its template, in the component's own image, against the clean case (tests/fixture-app for the PHP components, tests/eslint-clean for eslint, tests/secret-detection-clean for secret-detection, tests/sbom-clean for sbom) and the must-fail case in its fixture (tests/php-test-fails, tests/phpstan-fails, tests/pint-fails, tests/eslint-fails, a copy of the clean fixture carrying a token in src/config.php for secret-detection, built at run time so no secret-shaped string is committed, and tests/sbom-fails), in a copy in a temp dir. They exit 0 only when the clean case passes and the bad case fails with the expected finding. The .sh is the payload of a container; the .ps1 runs it with Docker. They need Docker; the contract job does not run them.

linux

docker run --rm -v "$(pwd):/app" -w /app php:8.3-cli-trixie sh tests/check-php-test-fails.sh
docker run --rm -v "$(pwd):/app" -v stack-composer-cache:/tmp/cache -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 sh tests/check-phpstan-fails.sh
docker run --rm -v "$(pwd):/app" -v stack-composer-cache:/tmp/cache -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 sh tests/check-pint-fails.sh
docker run --rm -v "$(pwd):/app" -w /app node:22.13-alpine@sha256:e2b39f7b64281324929257d0f8004fb6cb4bf0fdfb9aa8cedb235a766aec31da sh tests/check-eslint-fails.sh
docker run --rm --entrypoint sh -v "$(pwd):/app" -w /app zricethezav/gitleaks:v8.30.1@sha256:c00b6bd0aeb3071cbcb79009cb16a60dd9e0a7c60e2be9ab65d25e6bc8abbb7f tests/check-secret-detection-fails.sh
docker run --rm -v "$(pwd):/app" -v stack-composer-cache:/tmp/cache -e COMPOSER_CACHE_DIR=/tmp/cache -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 sh tests/check-sbom-fails.sh

windows

pwsh -File tests/check-php-test-fails.ps1
pwsh -File tests/check-phpstan-fails.ps1
pwsh -File tests/check-pint-fails.ps1
pwsh -File tests/check-eslint-fails.ps1
pwsh -File tests/check-secret-detection-fails.ps1
pwsh -File tests/check-sbom-fails.ps1

tests/check-composer-audit-fails.sh (and its .ps1 twin) does the same for composer-audit. It asserts the job has no allow_failure, no --ignore-unreachable and no swallowed exit code, renders the template's own script lines with each case's inputs, and runs them on copies of tests/fixture-app (must pass) and the locks in tests/audit-fixtures: advisory (laravel/framework v9.0.0, must fail naming CVE-2024-52301) and malware (aikido/endpoint-test 0.0.1, Aikido's harmless test package, must fail naming it on the malware list) in every abandoned mode, and abandoned, which must fail only in fail mode. composer audit asks Packagist for advisories and filter lists, so it needs the network; offline, the clean case fails, so it never passes by accident. The must-fail-composer-audit job runs it in CI. tests/check-abandoned-input.sh keeps the offline half (the input's default, regex and flag in the template and the contract) and runs in the contract job.

linux

docker run --rm -v "$(pwd):/app:ro" -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 sh tests/check-composer-audit-fails.sh

windows

pwsh -File tests/check-composer-audit-fails.ps1

tests/check-composer-ci-fails.sh (and its .ps1 twin) does the same for composer-ci. It asserts the job has no allow_failure, no --no-scripts or --ignore-platform-reqs on the install, no swallowed exit code on the composer ci line, and keeps interruptible: true and a timeout:, then renders the template's own script lines with each case's inputs and runs them on copies of the fixtures in tests/ci-fixtures: pass (must pass, naming ci-fixture-passed), fail (must fail, naming ci-fixture-failed) and a broken copy of pass whose composer.json is invalid JSON (must fail, so an install that cannot run never skips to green). The fixtures carry no packages, so the check needs no network. The must-fail-composer-ci job runs it in CI.

linux

docker run --rm -v "$(pwd):/app:ro" -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 sh tests/check-composer-ci-fails.sh

windows

pwsh -File tests/check-composer-ci-fails.ps1

tests/check-npm-audit-fails.sh (and its .ps1 twin) does the same for npm-audit. It asserts the job has no allow_failure, keeps the gate's exit code, carries --audit=true --offline=false and has no || true outside the full report, renders the template's own script with each case's inputs, and runs it on copies of tests/npm-audit-fails (lodash 4.17.20, GHSA-35jh-r3h4-6jhm: must fail at high, at medium and with an .npmrc that turns the audit off, and pass at critical) and tests/npm-audit-fixtures: clean (must pass), dev-only (passes with omit_dev true while the full report names the advisory, fails with false) and no-lock (passes with "nothing to audit"). A last case points npm at a closed local port and must fail the clean lock. npm audit asks the registry, so it needs the network; offline, the clean case fails, so it never passes by accident. The must-fail-npm-audit job runs it in CI.

linux

docker run --rm -v "$(pwd):/app:ro" -v stack-npm-cache:/root/.npm -w /app node:22.13-alpine@sha256:e2b39f7b64281324929257d0f8004fb6cb4bf0fdfb9aa8cedb235a766aec31da sh tests/check-npm-audit-fails.sh

windows

pwsh -File tests/check-npm-audit-fails.ps1

The Squire kit checks#

tests/check-renovate-squire-kit.sh (and .ps1) checks the preset's Squire rule: the exact two post-upgrade commands, the kit-files rule, and the squire_kit_tasks allow-list the renovate component writes. It compiles the commands for sample upgrades and checks that each one matches an allowed pattern, and that 22 hostile variants (shell operators, .. paths, another package or tool, an extra flag) match none. tests/check-squire-kit.sh (and .ps1) checks the squire-kit template: the version it reads, the install flags, squire init --check and its exit codes. The contract job runs both .sh files; the job itself runs on tests/squire-kit-fixture in Preflight's own pipeline.

Proof#

Proof runs against real Wayne State applications are on a private site, proof.apps.wayne.edu/preflight, behind a Wayne State employee sign-in. What was run, what held and what it caught in Preflight itself is on the public Proof page.

Docs#

The full documentation lives at preflight.apps.wayne.edu/docs/ on the project site, built from docs/ by Squire's docs builder. It starts with the overview page; the rest of the manual follows as the pages are written.

  • composer docs rebuilds site/docs/ from docs/; run it after editing a page.
  • composer docs:check fails when the built site is stale; composer ci runs it.

The pages are committed because the deploy server serves site/ without building. Every page links back to its Markdown, and the footer stamps the version the docs describe. Cleared for takeoff: the flight manual flies with the aircraft.

The pages wear the front page's flight deck: docs/_header.html is the front page's top bar and docs/theme/preflight.css maps its palette and B612 type onto the docs kit, with a dark mode taken from the instrument panel. docs/docs.json names both under theme. Restyle the docs in those two files, never in site/assets/docs.css or bin/docs-site.php: those are Squire's bytes.