W105.1-5 — Contract amendments for four Stable Life gaps plus exists/count collections #998

Workflow file for this run

.github/workflows/docs-ci.yml at bbb9fc4

	name: Docs CI

	# Everything documentation needs except deploy: check the authored Markdown,
	# then build the combined site (docs + landing page) to prove it still builds.
	# No path filters -- both jobs are meant to be required status checks, and a
	# required check that never runs leaves a pull request permanently blocked.
	#
	# The gate and the build are not the same check. Docusaurus fails on unresolved
	# routes inside the site; the gate covers what the site build never sees --
	# README.md, which is not part of the site at all, plus relative link targets,
	# heading anchors, product-name casing, and drift between a generated file and
	# its source. Neither one checks that the landing page (site/) still merges
	# cleanly onto the docs build -- that is what the verify job's extra steps are
	# for, so a PR proves the deploy path before it can run for real.

	"on":
	pull_request:
	push:
	branches:
	- main
	workflow_dispatch:

	permissions:
	contents: read
	packages: read

	defaults:
	run:
	shell: pwsh

	jobs:
	# --- DocumentationGate:start ---
	# The start/end markers are load-bearing: setup-docs.ps1 locates this exact
	# block by them to remove the job entirely when -SkipGate is passed. Keep
	# them if you edit this job by hand.
	documentation:
	name: Documentation links and terminology
	# Skipped on push to main, same as the verify job below: a push only
	# reaches main through a PR where this already ran as a required
	# check, so branch protection is what makes this skip safe rather
	# than a silent gap.
	if: github.event_name != 'push'
	runs-on: ubuntu-latest

	steps:
	- name: Check out repository
	uses: actions/checkout@v7

	# verification: true
	- name: Validate Markdown links, terminology, and generated files
	run: ./build/Test-Documentation.ps1
	# --- DocumentationGate:end ---

	verify:
	name: Verify Documentation Build
	# Skipped on push to main: docs-deploy.yml builds and deploys there, so
	# building again here would duplicate work every deploy performs anyway.
	if: github.event_name != 'push'
	runs-on: ubuntu-latest
	# Run inside the published base image, which already carries the
	# template under /template with node_modules and PowerShell installed.
	container:
	image: ghcr.io/the-running-dev/docs-template:latest
	credentials:
	username: ${{ github.repository_owner }}
	password: ${{ secrets.REGISTRY_TOKEN \|\| github.token }}

	steps:
	- name: Check out repository
	uses: actions/checkout@v7
	with:
	# Full history, not the default shallow clone -- the changelog step
	# below reads the whole `git log`.
	fetch-depth: 0

	# Regenerated fresh for every build, never committed -- replaces the old
	# recurring "chore: update changelog" pull request. `docs/docs/engine/
	# CHANGELOG.md` is still committed as a static fallback for anyone reading
	# the repository directly on GitHub; only the deployed site is guaranteed
	# current. Local `docs.ps1` preview still shows the committed (possibly
	# stale) copy -- its Docker build context is `docs/`, which cannot reach
	# this repo-root generator.
	- name: Regenerate changelog (build-only, not committed)
	run: \|
	# This job runs inside a container, so the checkout is owned by a
	# different uid than the one running it -- git refuses to touch it
	# ("dubious ownership") until explicitly trusted.
	git config --global --add safe.directory "$env:GITHUB_WORKSPACE"
	$body = & ./build/ConvertTo-Changelog.ps1 -RepoRoot . -RepositorySlug '${{ github.repository }}'
	$docsPage = @('---', 'slug: changelog', '---', '') + $body
	Set-Content -Path 'docs/docs/engine/CHANGELOG.md' -Value $docsPage -Encoding utf8NoBOM

	# verification: true
	- name: Build documentation
	run: /template/scripts/docs-build.ps1 -SourceDocs ./docs -OutputPath artifacts/docs

	- name: Cache Alpine Chromium packages
	uses: actions/cache@v4
	with:
	path: /tmp/apk-cache
	key: alpine-chromium-${{ runner.arch }}-v1

	# The landing page is a second, independent project (site/) sharing
	# this one GitHub Pages deployment: it serves "/", the docs serve
	# "/docs". The base image already has Node -- no setup-node needed.
	#
	# `check` runs format:check, lint, typecheck, the jsdom suite, the
	# real-browser suite (W65), and the build (site/package.json), not
	# just the build. A bare `build` would let a broken component
	# test, a real-browser regression, or a missing Open Graph tag
	# merge and deploy as long as the bundle still compiled -- `check`
	# is what a contributor runs locally before pushing, made a
	# required step here too, not a weaker CI-only substitute for it.
	# The real-browser suite needs Chromium installed first -- it is
	# not part of the base image, unlike Node. `playwright install
	# --with-deps` shells out to apt-get, but this container
	# (docs-template) is Alpine, so that step just fails outright
	# ("apt-get: not found"). Install Alpine's own `chromium` package
	# instead and point vitest.browser.config.ts at it via
	# PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH.
	# verification: true
	- name: Build and verify landing page
	env:
	PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH: /usr/bin/chromium-browser
	run: \|
	mkdir -p /tmp/apk-cache
	apk add --cache-dir /tmp/apk-cache chromium
	npm --prefix src/engine ci
	npm --prefix src/engine run build
	npm --prefix site ci
	npm --prefix site run check

	# Overlays the landing page onto the docs build -- overwrites the
	# docs build's generated-from-README root index.html, merges in
	# the landing page's assets, and refuses to proceed if anything
	# under artifacts/docs/docs/ changed. The package-backed `merge`
	# command (subzerodev-platform-ui-landing-page@0.2.0), invoked via
	# the site/package.json script site/scripts/verify-merge.mjs
	# already proved above in `npm --prefix site run check`.
	# verification: true
	- name: Merge landing page into documentation build
	run: npm --prefix site run merge

	# Run the same archiving step docs-deploy.yml uses, so the deploy
	# path is covered before merge rather than after it. This action
	# tars the site with `tar --hard-dereference`, which fails outright
	# on an image without GNU tar. Uploading an artifact publishes
	# nothing; deploy-pages does that, and it is not in this job.
	- name: Archive Pages artifact (verify deploy path)
	uses: actions/upload-pages-artifact@v5
	with:
	path: artifacts/docs

Navigation Menu

W105.1-5 — Contract amendments for four Stable Life gaps plus exists/count collections #998

Workflow file

W105.1-5 — Contract amendments for four Stable Life gaps plus exists/count collections #998

Uh oh!

Workflow file for this run