Files
coder/.github/workflows/test-docs-preview-mapper.sh
T
Nick Vigilante 13e673e9c2 ci: build docs PR previews on per-PR preview sites (#30698)
Docs previews at `coder.com/docs/@<branch>` share coder.com's origin and
cookies with the real site. This publishes each pull request's docs as
its own site on `docs.cdr-preview.dev`, a domain used only for previews
(repository variable `DOCS_PREVIEW_DOMAIN`), and points the existing
`docs-preview` comment's per-page links and checkboxes at it.

## URLs

- `https://pr-<n>.docs.cdr-preview.dev`: the PR head, re-aliased on
every build. A slower build of an older commit doesn't take it back.
- `https://pr-<n>-<first 9 of sha>.docs.cdr-preview.dev`: one per built
commit, listed newest first in a collapsible "Preview sites" list in the
PR's docs preview comment, so reviewers can step through the branch.
- Every URL is built from `vars.DOCS_PREVIEW_DOMAIN` (aliases, comment
links, cleanup); nothing hard-codes the domain. Previews moved off
`coderite.app`, which also hosts login-protected internal sites, so a
preview page whose content any coder/coder writer controls would have
been same-site with them. `cdr-preview.dev` hosts nothing else, and the
docs previews sit under `docs.` so other preview kinds can get their own
subdomain later. The jobs fail with a clear error if it is unset or a
`vercel.app` name, because `*.vercel.app` names are first-come across
all Vercel accounts and anyone could claim a preview's name before our
deploy or after cleanup frees it.
- Every preview carries the docs CSP and the other headers from
docs-engine's `apps/offlinedocs/vercel.json`, plus `X-Robots-Tag:
noindex`, which the deploy job prepends to the Build Output API
`config.json` routes without touching the existing ones.
- On merge or close, every deployment tagged `pr=<n>` and its aliases
are deleted. A weekly groom (Mondays 07:23 UTC, also
`workflow_dispatch`) deletes previews of any closed PR, in case a close
event was missed.

## Who gets previews

Only PRs from a branch in coder/coder, on every push that touches
`docs/**`. Every job in the deploy workflow, and the close path of the
cleanup, requires `github.event.pull_request.head.repo.full_name ==
github.repository`.

Fork PRs get no preview for now. Building fork content in a
`pull_request_target` run would share the base branch's Actions cache
scope, so a fork could poison main's cache, and it would sit beside the
private engine source. Fork previews come in a follow-up once the build
runs in a no-network sandbox (or the public builder kit ships). That
follow-up will gate on a maintainer stating the exact approved commit,
not on a label, so a push after approval can't slip in.

## One comment, posted only after a deploy

`docs-preview.yaml` is now a reusable workflow (`workflow_call` only).
The deploy workflow's `comment` job calls it after `deploy` succeeds, so
the per-page links never point at a preview that doesn't exist yet. I
chose this over moving the per-page logic into the deploy job: the
existing comment logic and its mapper test stay as they are, and only
the trigger changes.

Each PR gets at most one bot comment. The deploy job posts nothing; it
passes the built commit (`short_sha`) to `docs-preview.yaml`, which adds
a collapsible "Preview sites for each built commit" list to its comment,
newest first, read back from the comment on each run and capped at 100.
That comment is only posted when a non-generated page or an image
changed: a PR that changes only `docs/reference/**` (generated CLI and
API pages), or nothing previewable, gets no comment, and an earlier one
is deleted. Engineers found the earlier two-comment version too noisy.
If the comment is deleted that way and a later push brings it back, its
commit list starts over; the earlier previews still exist until the PR
closes.

## Three jobs, so PR content never runs beside a secret

1. `engine`: checks `DOCS_PREVIEW_DOMAIN` first, reads the docs-engine
commit pinned in `docs/.engine-ref` (from the PR head, falling back to
the base for a branch that predates the pin), mints a short-lived token
from a GitHub App installed only on coder/docs-engine, downscoped to
`contents: read` on that one repository, checks out with
`persist-credentials: false`, and uploads a tarball plus its sha256 as a
job output. Never touches PR content.
2. `build`: no secrets, `contents: read` only. Verifies the engine
tarball against the digest, sparse-checks out the PR's `docs/`, refuses
a `docs/` that is or contains a symbolic link (one could pull runner
files, such as the private engine source, into a public preview), builds
`apps/offlinedocs` with `DOCS_ROOT` as docs-engine's own
`docs-pr-preview.yml` does, and uploads only the static `out/` export.
3. `deploy`: in the `docs-preview` environment with
`VERCEL_PREVIEW_TOKEN`. Verifies the engine tarball against the digest
again (a compromised build job could replace an artifact, but not a job
output), refuses an export holding anything but regular files and
directories, lays the static files out with the engine's `build:output`
script, adds noindex, runs `vercel deploy --prebuilt` with meta `pr` and
`sha`, and sets both aliases through the Vercel API. It holds only
`pull-requests: read`, for the check that the PR head hasn't moved
before re-aliasing; the `comment` job posts the comment. It runs the
engine's trusted script rather than taking `config.json` from the build
job, because a Build Output directory from another job could carry
serverless functions or rewritten routes.

`docs-pr-preview-cleanup.yaml` keeps `pull_request_target: closed` so a
PR can't change its own cleanup; it checks out nothing and runs no PR
content, only Vercel and GitHub API calls. Fork PRs have no previews, so
their close is skipped.

PR-chosen strings never reach a log line unfiltered: the comment
workflow prints changed reference-page paths with every character
outside a path allowlist as `?`, so a file name can't forge a `::` or
`##[` workflow command, and the deploy job's errors name no path.

## Engine pin

`docs/.engine-ref` now pins docs-engine `main` at `eadb477`, the engine
`coder.com/docs` launched with on 2026-10-28 (was `e3c55c2`; an earlier
revision of this PR pinned `5584d67`). The commands the workflow runs
are unchanged between them. `e3c55c2` already had the `build:output`
script, but the newer engine refuses a symlinked docs root, renders
search hits without raw HTML, drops author-chosen heading ids that could
break hydration, and pins Node 22.23.4, which the build and deploy jobs
now use too. The commands the workflow runs (`pnpm turbo run build
--filter=@coder/offlinedocs` and
`apps/offlinedocs/scripts/build-output.mjs`) are unchanged at `5584d67`.

The pin must be a commit on docs-engine `main`. The `engine` job checks
docs-engine out with full history and fails before packing unless `git
merge-base --is-ancestor "$REF" origin/main` passes. Once docs-engine is
public, a commit pushed to any fork of it can be fetched by SHA through
`coder/docs-engine`, so the 40-hex format check alone would let a PR
build with unreviewed engine code. `test-docs-preview-mapper.sh` pins
that the check runs in the `engine` job, before the pack step, against a
full-history checkout.

## Before this can run

Checked on 2026-11-12: IT registered `cdr-preview.dev` in Vercel on team
`team_tGkWfhEGGelkkqUUm9nXq17r`, with Vercel nameservers, so
`*.docs.cdr-preview.dev` needs no DNS or wildcard step. IT also set
`docs.cdr-preview.dev` as the `coder-docs-pr-preview` project's own
preview deployment suffix and removed `coderite.app` from it, so the
project's generated deployment URLs land on the preview domain too, not
on the team's `coderite.app` suffix; the first deploy will confirm that.
The project has Vercel Authentication and password protection off. The
secrets `DOCS_ENGINE_APP_ID` and `DOCS_ENGINE_APP_PRIVATE_KEY` exist.
`DOCS_PREVIEW_DOMAIN` is set to `docs.cdr-preview.dev`. The
`docs-preview` environment exists (created 2026-10-28) with no
protection rules and no branch policy, and holds `VERCEL_PREVIEW_ORG_ID`
and `VERCEL_PREVIEW_PROJECT_ID`, and `VERCEL_PREVIEW_TOKEN` was stored
on 2026-11-12.

- [ ] **GitHub App** (org owner; requested in DOCS-1739). Confirm the
app behind `DOCS_ENGINE_APP_ID` is installed on coder/docs-engine only
("Only select repositories") with Repository permissions Contents:
Read-only and Metadata: Read-only and nothing else, at
https://github.com/organizations/coder/settings/installations. The
workflow also downscopes each token to `contents: read` on docs-engine,
so the installation is the outer bound.
- [x] **Repository variable**, set on 2026-11-12. Set it at repository
level, not on the environment, because the `engine` job and
`docs-preview.yaml` run outside it:
  ```sh
gh variable set DOCS_PREVIEW_DOMAIN -R coder/coder --body
docs.cdr-preview.dev
  ```
- [x] **Vercel Authentication off** on `coder-docs-pr-preview`
(`prj_RiVa1voPHmsfbEXkasFDXmYqAr0L`): checked on 2026-11-12,
`ssoProtection` and `passwordProtection` both report `enabled: false`.
- [x] **Preview domain** (IT): `cdr-preview.dev` registered with Vercel
nameservers, and `docs.cdr-preview.dev` set as the project's preview
deployment suffix.
- [x] **Project-scoped Vercel token**, 90-day expiry (created
2026-11-12, expires about 2027-02-10; a rotation reminder is set for
2027-02-09). The three checks below returned `200`, `404` and `403`.
Create it at https://vercel.com/account/settings/tokens, scoped to the
`coder-docs-pr-preview` project only (`vercel tokens create --project`
is refused for non-owners). Then check, with the new token in
`$VERCEL_PREVIEW_TOKEN`, that it can list the project's deployments
(`200`), reach the team-level alias API (`404`, not `403`), and cannot
see the production `coder-docs` project (`403` or `404`, never `200`):
  ```sh
curl -sS -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer
$VERCEL_PREVIEW_TOKEN" \

"https://api.vercel.com/v6/deployments?teamId=team_tGkWfhEGGelkkqUUm9nXq17r&projectId=prj_RiVa1voPHmsfbEXkasFDXmYqAr0L&limit=1"
curl -sS -o /dev/null -w '%{http_code}\n' -X DELETE -H "Authorization:
Bearer $VERCEL_PREVIEW_TOKEN" \

"https://api.vercel.com/v2/aliases/pr-0.docs.cdr-preview.dev?teamId=team_tGkWfhEGGelkkqUUm9nXq17r"
curl -sS -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer
$VERCEL_PREVIEW_TOKEN" \

"https://api.vercel.com/v6/deployments?teamId=team_tGkWfhEGGelkkqUUm9nXq17r&projectId=prj_pC4y7hjUgcsYYNoSDL7pNJnafzh3&limit=1"
  ```
- [x] **`docs-preview` environment**: it exists with no branch policy
(because `pull_request` runs on the merge ref) and its two variables are
set. Only the token is left:
  ```sh
  gh secret set VERCEL_PREVIEW_TOKEN -R coder/coder --env docs-preview
  ```
`gh secret set` prompts for the token so it stays out of shell history.
- [ ] **Security sign-off** (Lisa), on these points:
- **Preview domain.** Previews now live on `docs.cdr-preview.dev`, which
hosts nothing else, so they are no longer same-site with the
login-protected sites on `coderite.app`. Previews are same-site with
each other, so one PR's preview could set a cookie the others receive.
Anything added to `cdr-preview.dev` later should stay outside `docs.`
and not rely on cookies scoped to the parent domain. The docs CSP allows
inline scripts, and any coder/coder writer controls a preview's content.
- Any coder/coder writer can reach `VERCEL_PREVIEW_TOKEN` by editing the
workflow on a branch, as with any secret a `pull_request` deploy uses.
The token is scoped to the one preview project to bound that; required
reviewers on the environment would close it, at the cost of an approval
per preview.
- The engine commit comes from the PR's `docs/.engine-ref`, so the
engine code that lays out the export in the deploy job is PR-chosen, but
only among commits on docs-engine `main`. It runs before, not in, the
step that holds the token.
- [ ] **Mark ready for review** once the items above are done and a docs
push to this PR has produced a working preview.

## Testing

`test-docs-preview-mapper.sh` checks that `docs-preview.yaml` reads the
domain from `vars.DOCS_PREVIEW_DOMAIN`, builds links on
`pr-<n>.<domain>` from the validated value with no `coder.com/docs/@` or
`vercel.app` link, and runs only as a reusable workflow called after
`deploy`. It also checks the per-commit list (this commit first, earlier
ones carried, repeats and other PRs' lines dropped, capped at 100), that
the list round-trips through the comment it renders without touching
checkbox state, and that the deploy job posts no comment and passes its
commit on. All 58 checks pass (run with GNU coreutils, sed, grep and awk
on macOS); the new workflow check failed before the change. `actionlint`
at the repo's pinned commit, with ShellCheck, reports nothing, and so
does the repo's pinned zizmor 1.11.0 (`--strict-collection
--persona=regular`). The noindex step was run against a `config.json`
from docs-engine's real `build-output.mjs`: the route count went from 11
to 12 with the CSP route intact. With the variable, environment and
token in place, the `engine` and `build` jobs pass on this PR, including
the check that the pinned engine commit is on docs-engine `main`. The
first deploy failed at `vercel pull` with "Could not retrieve Project
Settings": Vercel CLI 59.3.0 looks up the token's team (403 for a
project-scoped token) and gives up, although the token reads the project
(200). Run locally with the same token, 65.11.0 skips that lookup and
pulls the settings, so the workflow now pins 65.11.0, the newest release
more than a week old. The deploy, alias and cleanup calls have not
completed in CI yet.

---
🤖 Built with AI assistance.
2026-11-12 14:10:21 -05:00

1065 lines
46 KiB
Bash
Executable File

#!/bin/bash
# Regression tests for the logic-dense pieces of docs-preview.yaml: the
# path mapper (five case branches, all covered here), manifest path
# extraction, changed-file/image filtering, the eligible-set intersection,
# checkbox-state parsing, and the checked-state carryover. Where the
# workflow runs jq, these run the same jq against fixtures rather than a
# shell mirror. Keep in sync with docs-preview.yaml.
set -euo pipefail
# map_doc_path replicates the case block from docs-preview.yaml so
# we can exercise it without running the full workflow.
map_doc_path() {
local doc_path="$1"
local rel="${doc_path#docs/}"
local page_path
case "$rel" in
README.md)
page_path=""
;;
*)
local base dir stripped
base="$(basename "$rel")"
dir="$(dirname "$rel")"
if [ "$dir" = "." ]; then
dir=""
fi
case "$base" in
index.md | README.md)
page_path="$dir"
;;
*)
stripped="${base%.md}"
if [ -z "$dir" ]; then
page_path="$stripped"
else
page_path="${dir}/${stripped}"
fi
;;
esac
;;
esac
printf '%s' "$page_path"
}
failures=0
assert_maps_to() {
local input="$1"
local expected="$2"
local actual
actual="$(map_doc_path "$input")"
if [ "$actual" = "$expected" ]; then
echo "PASS: $input -> \"$expected\""
else
echo "FAIL: $input -> \"$actual\" (expected \"$expected\")"
failures=$((failures + 1))
fi
}
# Branch 1: top-level README maps to the docs root.
assert_maps_to "docs/README.md" ""
# Branch 2: nested index.md strips the filename, leaving the dir.
assert_maps_to "docs/install/index.md" "install"
# Branch 3: nested README.md behaves the same as index.md.
assert_maps_to "docs/admin/README.md" "admin"
# Branch 4: nested regular file strips .md and keeps the dir prefix.
assert_maps_to "docs/ai-coder/tasks.md" "ai-coder/tasks"
# Branch 5: top-level non-README file strips .md with no dir prefix.
assert_maps_to "docs/CHANGELOG.md" "CHANGELOG"
# Additional coverage for edge cases and deeper nesting.
assert_maps_to "docs/index.md" ""
assert_maps_to "docs/admin/security/audit-logs.md" "admin/security/audit-logs"
assert_maps_to "docs/admin/groups.md" "admin/groups"
assert_maps_to "docs/tutorials/best-practices/index.md" "tutorials/best-practices"
# normalize_manifest_path replicates the sed pipeline docs-preview.yaml runs
# over the manifest paths. Entries are written "./foo/bar.md" or "foo/bar.md"
# relative to docs/; both must normalize to "docs/foo/bar.md" to compare
# against the PR-files API filenames.
normalize_manifest_path() {
printf '%s' "$1" | sed -E 's#^\./##; s#^#docs/#'
}
assert_normalizes_to() {
local input="$1"
local expected="$2"
local actual
actual="$(normalize_manifest_path "$input")"
if [ "$actual" = "$expected" ]; then
echo "PASS: normalize($input) -> \"$expected\""
else
echo "FAIL: normalize($input) -> \"$actual\" (expected \"$expected\")"
failures=$((failures + 1))
fi
}
# Branch A: manifest path with the "./" prefix most entries use.
assert_normalizes_to "./about/screenshots.md" "docs/about/screenshots.md"
# Branch B: manifest path with no prefix, as some entries have (for
# example everything under reference/cli/ in the real manifest).
assert_normalizes_to "reference/cli/whoami.md" "docs/reference/cli/whoami.md"
# Branch C: top-level README, no subdirectory.
assert_normalizes_to "./README.md" "docs/README.md"
# parse_checkbox_line replicates the sed extraction docs-preview.yaml runs
# over the comment body to recover the live checked state a reviewer's clicks
# land in (GitHub persists a toggle as a comment-body edit). Emits
# "<x-or-space>\t<path>", the workflow's intermediate TSV.
parse_checkbox_line() {
# shellcheck disable=SC2016 # backticks are literal Markdown code-span delimiters, not command substitution.
printf '%s\n' "$1" | grep -oE '^[[:space:]]*- \[[ xX]\] \[`[^`]+`\]' | sed -E 's/^[[:space:]]*- \[([ xX])\] \[`([^`]+)`\]/\1\t\2/' || true
}
assert_checkbox_parses_to() {
local input="$1"
local expected="$2"
local actual
actual="$(parse_checkbox_line "$input")"
if [ "$actual" = "$expected" ]; then
echo "PASS: parse_checkbox($input) -> \"$expected\""
else
echo "FAIL: parse_checkbox($input) -> \"$actual\" (expected \"$expected\")"
failures=$((failures + 1))
fi
}
# Branch A: a checked page.
# shellcheck disable=SC2016 # backtick-quoted path in the fixture is literal Markdown, not command substitution.
assert_checkbox_parses_to '- [x] [`docs/foo/bar.md`](https://pr-1.docs.cdr-preview.dev/foo/bar)' "$(printf 'x\tdocs/foo/bar.md')"
# Branch B: an unchecked page.
# shellcheck disable=SC2016
assert_checkbox_parses_to '- [ ] [`docs/foo/baz.md`](https://pr-1.docs.cdr-preview.dev/foo/baz)' "$(printf ' \tdocs/foo/baz.md')"
# Branch C: an uppercase X, which GitHub also renders as checked.
# shellcheck disable=SC2016
assert_checkbox_parses_to '- [X] [`docs/foo/qux.md`](https://pr-1.docs.cdr-preview.dev/foo/qux)' "$(printf 'X\tdocs/foo/qux.md')"
# Branch D: a non-checklist line (prose, a header, the hidden markers)
# must not match at all.
assert_checkbox_parses_to '## Docs preview' ""
# round_trip_state exercises the actual jq/grep/sed/base64 from
# docs-preview.yaml end to end: a path->sha map is encoded into the hidden
# marker, read back, the live checkbox glyphs parsed, and the carryover jq
# decides each page's final checked state.
STATE_PREFIX='docs-preview-state:'
# Recovers the {path: sha} map from the hidden marker, mirroring the guarded
# block in docs-preview.yaml: adopt the decode only if non-empty and a JSON
# object, else {}. The non-empty check keeps the outcome the same on
# jq < 1.7, where `jq -e` exits 0 on empty input.
recover_old_state() {
local body="$1" b64 decoded
b64=$(printf '%s\n' "$body" | grep -oE "${STATE_PREFIX}[A-Za-z0-9+/=]+" | sed "s/^${STATE_PREFIX}//") || true
if [ -n "$b64" ]; then
decoded=$(printf '%s' "$b64" | base64 -d 2>/dev/null || true)
if [ -n "$decoded" ] && printf '%s' "$decoded" | jq -e 'type == "object"' >/dev/null 2>&1; then
printf '%s' "$decoded"
return
fi
fi
printf '{}'
}
# Recovers the {path: checked} map from the rendered checklist,
# replicating the grep|sed|jq pipeline in docs-preview.yaml.
recover_old_checked() {
# shellcheck disable=SC2016 # backticks are literal Markdown code-span delimiters, not command substitution.
printf '%s\n' "$1" |
grep -oE '^[[:space:]]*- \[[ xX]\] \[`[^`]+`\]' |
sed -E 's/^[[:space:]]*- \[([ xX])\] \[`([^`]+)`\]/\1\t\2/' |
jq -R -s '[splits("\n") | select(length > 0) | split("\t") | {(.[1]): (.[0] | test("x"; "i"))}] | add // {}'
}
# Runs the carryover jq from docs-preview.yaml over the recovered maps.
decide_rows() {
jq -n \
--argjson eligible "$1" \
--argjson old_state "$2" \
--argjson old_checked "$3" \
'[
$eligible[] | . as $f |
($old_state[$f.filename] // null) as $prev_sha |
(if $prev_sha != null and $prev_sha == $f.sha
then ($old_checked[$f.filename] // false)
else false
end) as $checked |
{filename: $f.filename, sha: $f.sha, checked: $checked}
] | sort_by(.filename)' | jq -c .
}
assert_round_trip_state() {
local old_state_json='{"docs/a.md":"sha1","docs/b.md":"sha1","docs/c.md":"sha1","docs/e.md":"sha1"}'
local state_b64
state_b64=$(printf '%s' "$old_state_json" | base64 -w0)
# A rendered comment body with the hidden state marker: a.md checked,
# b.md and c.md unchecked, and no checklist line for e.md (it is in
# the state marker but absent from the list).
local body
# shellcheck disable=SC2016 # backtick-quoted paths are literal Markdown.
body=$(printf '%s\n' \
'## Docs preview' \
'' \
'- [x] [`docs/a.md`](https://pr-1.docs.cdr-preview.dev/a)' \
'- [ ] [`docs/b.md`](https://pr-1.docs.cdr-preview.dev/b)' \
'- [x] [`docs/c.md`](https://pr-1.docs.cdr-preview.dev/c)' \
'<!-- docs-preview -->' \
"<!-- ${STATE_PREFIX}${state_b64} -->")
# a.md: sha unchanged, was checked -> stays checked.
# b.md: sha unchanged, was unchecked -> stays unchecked.
# c.md: sha changed, was checked -> resets to unchecked.
# d.md: brand-new, absent from state -> // null -> unchecked.
# e.md: sha unchanged, absent from list -> // false -> unchecked.
local eligible_json='[{"filename":"docs/a.md","sha":"sha1"},{"filename":"docs/b.md","sha":"sha1"},{"filename":"docs/c.md","sha":"sha2"},{"filename":"docs/d.md","sha":"sha9"},{"filename":"docs/e.md","sha":"sha1"}]'
local rec_state rec_checked actual expected
rec_state=$(recover_old_state "$body")
rec_checked=$(recover_old_checked "$body")
actual=$(decide_rows "$eligible_json" "$rec_state" "$rec_checked")
expected='[{"filename":"docs/a.md","sha":"sha1","checked":true},{"filename":"docs/b.md","sha":"sha1","checked":false},{"filename":"docs/c.md","sha":"sha2","checked":false},{"filename":"docs/d.md","sha":"sha9","checked":false},{"filename":"docs/e.md","sha":"sha1","checked":false}]'
if [ "$actual" = "$expected" ]; then
echo "PASS: round_trip_state carryover"
else
echo "FAIL: round_trip_state carryover -> $actual (expected $expected)"
failures=$((failures + 1))
fi
}
assert_round_trip_state
# A malformed marker must recover to {} with the run surviving. Feed markers
# that clear the charset grep but fail the decode or the object-type gate.
assert_marker_recovers() {
local marker="$1" expected="$2" desc="$3" body actual
body=$(printf '## Docs preview\n<!-- docs-preview -->\n<!-- %s%s -->' "$STATE_PREFIX" "$marker")
actual=$(recover_old_state "$body")
if [ "$actual" = "$expected" ]; then
echo "PASS: recover_old_state ($desc) -> $expected"
else
echo "FAIL: recover_old_state ($desc) -> $actual (expected $expected)"
failures=$((failures + 1))
fi
}
# A valid object marker recovers to the object verbatim.
assert_marker_recovers "$(printf '{"docs/a.md":"sha1"}' | base64 -w0)" '{"docs/a.md":"sha1"}' "valid object"
# Charset-valid but undecodable base64 (odd length) degrades to {}.
assert_marker_recovers "A" "{}" "undecodable base64"
# Valid base64 of a non-object (a JSON string) fails the type gate -> {}.
assert_marker_recovers "$(printf '"hello"' | base64 -w0)" "{}" "valid base64 non-object"
# Valid base64 that decodes to non-JSON bytes fails the parse gate -> {}.
assert_marker_recovers "$(printf '\xff\xfe\xfd' | base64 -w0)" "{}" "valid base64 non-JSON bytes"
# extract_manifest_paths runs the real jq + sed pipeline from
# docs-preview.yaml against manifest JSON on stdin, guarding the recursive
# path extraction that normalize_manifest_path above does not reach.
extract_manifest_paths() {
jq -r '[.. | objects | select(has("path")) | .path] | .[]' |
sed -E 's#^\./##; s#^#docs/#'
}
# Manifest fixture in the real schema: "./"-prefixed and bare paths, a
# nested child, and an object with only icon_path (no "path" key) that
# must not be collected.
manifest_fixture='{"versions":["main"],"routes":[
{"title":"Home","path":"./README.md","icon_path":"./images/home.svg"},
{"title":"Install","path":"./install/index.md","children":[
{"title":"CLI","path":"reference/cli/whoami.md"}
]},
{"title":"IconOnly","icon_path":"./images/x.svg"}
]}'
actual_paths=$(printf '%s' "$manifest_fixture" | extract_manifest_paths | LC_ALL=C sort | tr '\n' ' ')
expected_paths="docs/README.md docs/install/index.md docs/reference/cli/whoami.md "
if [ "$actual_paths" = "$expected_paths" ]; then
echo "PASS: extract_manifest_paths (icon_path-only object excluded)"
else
echo "FAIL: extract_manifest_paths -> \"$actual_paths\" (expected \"$expected_paths\")"
failures=$((failures + 1))
fi
# filter_changed_files runs the real pulls/files filter jq from
# docs-preview.yaml: keep non-removed docs/*.md outside docs/.style/,
# emitting <filename>\t<sha>.
filter_changed_files() {
jq -r '.[] | select(.status != "removed") | select(.filename | test("^docs/.*\\.md$")) | select((.filename | test("^docs/\\.style/")) | not) | select((.filename | test("^docs/reference/")) | not) | [.filename, .sha] | @tsv'
}
files_fixture='[
{"filename":"docs/admin/index.md","sha":"aaa","status":"modified"},
{"filename":"docs/ai-coder/tasks.md","sha":"bbb","status":"added"},
{"filename":"docs/old.md","sha":"ccc","status":"removed"},
{"filename":"docs/.style/word-list.txt","sha":"ddd","status":"modified"},
{"filename":"docs/images/diagram.png","sha":"eee","status":"added"},
{"filename":"site/README.md","sha":"fff","status":"modified"},
{"filename":"docs/.style/rules.md","sha":"ggg","status":"modified"},
{"filename":"docs/reference/cli/whoami.md","sha":"hhh","status":"modified"}
]'
actual_changed=$(printf '%s' "$files_fixture" | filter_changed_files | LC_ALL=C sort | tr '\n' '|')
expected_changed="$(printf 'docs/admin/index.md\taaa\ndocs/ai-coder/tasks.md\tbbb\n' | tr '\n' '|')"
if [ "$actual_changed" = "$expected_changed" ]; then
echo "PASS: filter_changed_files (removed/.style/reference/non-md/non-docs excluded)"
else
echo "FAIL: filter_changed_files -> \"$actual_changed\" (expected \"$expected_changed\")"
failures=$((failures + 1))
fi
# filter_reference_files: the pages excluded above, logged instead of dropped.
filter_reference_files() {
jq -r '.[] | select(.status != "removed") | select(.filename | test("^docs/reference/.*\\.md$")) | [.filename, .sha] | @tsv'
}
actual_reference=$(printf '%s' "$files_fixture" | filter_reference_files | LC_ALL=C sort | tr '\n' '|')
expected_reference="$(printf 'docs/reference/cli/whoami.md\thhh\n' | tr '\n' '|')"
if [ "$actual_reference" = "$expected_reference" ]; then
echo "PASS: filter_reference_files (only generated reference pages, removed excluded)"
else
echo "FAIL: filter_reference_files -> \"$actual_reference\" (expected \"$expected_reference\")"
failures=$((failures + 1))
fi
# intersect_eligible replicates the grep -qxF intersection from
# docs-preview.yaml: keep only changed files whose path is in the manifest
# allowlist.
intersect_eligible() {
local changed="$1" allowed="$2"
printf '%s\n' "$changed" | while IFS=$'\t' read -r filename sha; do
[ -z "$filename" ] && continue
if printf '%s\n' "$allowed" | grep -qxF "$filename"; then
printf '%s\t%s\n' "$filename" "$sha"
fi
done
}
changed_tsv_fixture="$(printf 'docs/admin/index.md\taaa\ndocs/ai-coder/tasks.md\tbbb\ndocs/not-in-manifest.md\tccc')"
allowed_fixture="$(printf 'docs/admin/index.md\ndocs/ai-coder/tasks.md\ndocs/install/index.md')"
actual_eligible=$(intersect_eligible "$changed_tsv_fixture" "$allowed_fixture" | LC_ALL=C sort | tr '\n' '|')
expected_eligible="$(printf 'docs/admin/index.md\taaa\ndocs/ai-coder/tasks.md\tbbb\n' | tr '\n' '|')"
if [ "$actual_eligible" = "$expected_eligible" ]; then
echo "PASS: intersect_eligible (drops paths not in the manifest)"
else
echo "FAIL: intersect_eligible -> \"$actual_eligible\" (expected \"$expected_eligible\")"
failures=$((failures + 1))
fi
# filter_changed_images runs the real image filter jq from docs-preview.yaml:
# keep non-removed docs/ images outside docs/.style/, extensions matched
# case-insensitively (no sha; the image section is stateless).
filter_changed_images() {
jq -r '.[] | select(.status != "removed") | select(.filename | test("^docs/.*\\.(png|jpe?g|gif|svg|webp|avif|bmp|ico)$"; "i")) | select((.filename | test("^docs/\\.style/")) | not) | .filename'
}
images_fixture='[
{"filename":"docs/images/a.png","sha":"a1","status":"modified"},
{"filename":"docs/images/user-guides/b.SVG","sha":"b1","status":"added"},
{"filename":"docs/images/c.jpg","sha":"c1","status":"added"},
{"filename":"docs/images/d.jpeg","sha":"d1","status":"added"},
{"filename":"docs/images/e.gif","sha":"e1","status":"added"},
{"filename":"docs/images/f.webp","sha":"f1","status":"added"},
{"filename":"docs/images/g.avif","sha":"g2","status":"added"},
{"filename":"docs/images/h.bmp","sha":"h1","status":"added"},
{"filename":"docs/images/i.ico","sha":"i1","status":"added"},
{"filename":"docs/images/old.gif","sha":"g1","status":"removed"},
{"filename":"docs/.style/logo.png","sha":"s1","status":"modified"},
{"filename":"docs/admin/notes.md","sha":"m1","status":"modified"},
{"filename":"docs/images/clip.mp4","sha":"v1","status":"added"},
{"filename":"site/logo.png","sha":"x1","status":"modified"}
]'
actual_images=$(printf '%s' "$images_fixture" | filter_changed_images | LC_ALL=C sort | tr '\n' '|')
# Every extension in the workflow regex (png, jpg, jpeg, gif, svg, webp,
# avif, bmp, ico) has a matching entry, so trimming any one from the regex
# fails this assertion. b.SVG also proves the match is case-insensitive.
expected_images="docs/images/a.png|docs/images/c.jpg|docs/images/d.jpeg|docs/images/e.gif|docs/images/f.webp|docs/images/g.avif|docs/images/h.bmp|docs/images/i.ico|docs/images/user-guides/b.SVG|"
if [ "$actual_images" = "$expected_images" ]; then
echo "PASS: filter_changed_images (every extension matches; removed/.style/md/non-docs/video excluded, case-insensitive)"
else
echo "FAIL: filter_changed_images -> $actual_images (expected $expected_images)"
failures=$((failures + 1))
fi
# extract_ref_tokens, resolve_ref, and pages_for_image are spliced in
# verbatim from docs-preview.yaml so the mirror can't drift; the assertions
# below drive them against a throwaway docs tree. A page embeds an image only
# when a Markdown/HTML reference resolves to exactly that repo path, so prose
# mentions and same-basename collisions elsewhere don't match.
extract_ref_tokens() {
local file="$1"
# Markdown: capture up to the first space or ) so an optional
# "title" after the path is dropped.
grep -oE '!\[[^]]*\]\([^)[:space:]]+' "$file" 2>/dev/null |
sed -E 's/^!\[[^]]*\]\(//' || true
# HTML: single- or double-quoted src, case-insensitive tag/attr.
grep -oiE '<img[^>]+src=("[^"]+"|'\''[^'\'']+'\'')' "$file" 2>/dev/null |
sed -E 's/.*src=//I; s/^["'\'']//; s/["'\'']$//' || true
}
resolve_ref() {
local file="$1" ref="$2" dir
ref="${ref%%#*}"
ref="${ref%%\?*}"
ref="${ref#<}"
ref="${ref%>}"
[ -z "$ref" ] && return 0
case "$ref" in
*://* | //* | mailto:* | data:*) return 0 ;;
esac
dir=$(dirname "$file")
realpath -m --relative-to="$PWD" "${PWD}/${dir}/${ref}" 2>/dev/null || true
}
pages_for_image() {
local image="$1" base candidates file token
base=$(basename "$image")
candidates=$(grep -rlF "$base" docs --include='*.md' 2>/dev/null |
grep -v '^docs/\.style/' || true)
[ -z "$candidates" ] && return 0
while IFS= read -r file; do
[ -z "$file" ] && continue
while IFS= read -r token; do
[ -z "$token" ] && continue
[ "$(basename "$token")" = "$base" ] || continue
if [ "$(resolve_ref "$file" "$token")" = "$image" ]; then
printf '%s\n' "$file"
break
fi
done < <(extract_ref_tokens "$file")
done <<<"$candidates"
}
img_fixture_root=$(mktemp -d)
img_orig_pwd=$PWD
mkdir -p \
"$img_fixture_root/docs/user-guides" \
"$img_fixture_root/docs/admin/sub" \
"$img_fixture_root/docs/images/other" \
"$img_fixture_root/docs/.style"
# Two pages embed docs/images/shared.png at different depths (one Markdown,
# one HTML): the nested-list case.
cat >"$img_fixture_root/docs/user-guides/page.md" <<'MD'
# UG
![shot](../images/shared.png)
MD
cat >"$img_fixture_root/docs/admin/sub/deep.md" <<'MD'
# Sub
<img src="../../images/shared.png" alt="x">
MD
# A different shared.png in another dir must not cross-match.
cat >"$img_fixture_root/docs/admin/collide.md" <<'MD'
# Other
![o](../images/other/shared.png)
MD
# Only a prose mention of the basename must not match.
cat >"$img_fixture_root/docs/admin/prose.md" <<'MD'
# Prose
We refreshed shared.png last week.
MD
# An external image with the same basename must be ignored.
cat >"$img_fixture_root/docs/admin/ext.md" <<'MD'
# Ext
![e](https://example.com/shared.png)
MD
# A .style page that references it is excluded by pages_for_image.
cat >"$img_fixture_root/docs/.style/tool.md" <<'MD'
# Style
![s](../images/shared.png)
MD
cd "$img_fixture_root"
actual_pfi=$(pages_for_image "docs/images/shared.png" | LC_ALL=C sort | tr '\n' '|')
expected_pfi="docs/admin/sub/deep.md|docs/user-guides/page.md|"
if [ "$actual_pfi" = "$expected_pfi" ]; then
echo "PASS: pages_for_image (md+html refs match; prose/external/.style excluded)"
else
echo "FAIL: pages_for_image -> $actual_pfi (expected $expected_pfi)"
failures=$((failures + 1))
fi
actual_collide=$(pages_for_image "docs/images/other/shared.png" | LC_ALL=C sort | tr '\n' '|')
expected_collide="docs/admin/collide.md|"
if [ "$actual_collide" = "$expected_collide" ]; then
echo "PASS: pages_for_image (same-basename images in different dirs don't cross-match)"
else
echo "FAIL: pages_for_image collision -> $actual_collide (expected $expected_collide)"
failures=$((failures + 1))
fi
cd "$img_orig_pwd"
rm -rf "$img_fixture_root"
# resolve_ref branch coverage: each normalization step (strip #fragment,
# ?query, <...> wrapper; reject external and protocol-relative refs) has a
# case, so deleting any one fails the suite. Path math is relative to $PWD,
# so these are independent of the real tree.
assert_resolves_ref() {
local ref="$1" expected="$2" desc="$3" actual
actual=$(resolve_ref "docs/user-guides/page.md" "$ref")
if [ "$actual" = "$expected" ]; then
echo "PASS: resolve_ref ($desc)"
else
echo "FAIL: resolve_ref ($desc) -> \"$actual\" (expected \"$expected\")"
failures=$((failures + 1))
fi
}
assert_resolves_ref "../images/shared.png" "docs/images/shared.png" "relative path"
assert_resolves_ref "../images/shared.png#top" "docs/images/shared.png" "strips #fragment"
assert_resolves_ref "../images/shared.png?v=1" "docs/images/shared.png" "strips ?query"
assert_resolves_ref "<../images/shared.png>" "docs/images/shared.png" "strips <...> wrapper"
assert_resolves_ref "https://example.com/shared.png" "" "external URL ignored"
assert_resolves_ref "//cdn.example.com/shared.png" "" "protocol-relative ignored"
assert_resolves_ref "mailto:docs@coder.com" "" "mailto ignored"
assert_resolves_ref "" "" "empty ref"
# extract_ref_tokens branch coverage: a titled Markdown ref (the space stops
# the path capture), an uppercase <IMG SRC="..."> (case-insensitive grep),
# and a single-quoted src.
ert_root=$(mktemp -d)
cat >"$ert_root/titled.md" <<'MD'
![shot](../images/shared.png "Optional title")
MD
cat >"$ert_root/upper.md" <<'MD'
<IMG SRC="../images/shared.png" alt="x">
MD
cat >"$ert_root/single.md" <<'MD'
<img src='../images/shared.png'>
MD
assert_extracts() {
local file="$1" expected="$2" desc="$3" actual
actual=$(extract_ref_tokens "$file" | tr '\n' '|')
if [ "$actual" = "$expected" ]; then
echo "PASS: extract_ref_tokens ($desc)"
else
echo "FAIL: extract_ref_tokens ($desc) -> \"$actual\" (expected \"$expected\")"
failures=$((failures + 1))
fi
}
assert_extracts "$ert_root/titled.md" "../images/shared.png|" "titled Markdown ref drops the title"
assert_extracts "$ert_root/upper.md" "../images/shared.png|" "uppercase <IMG SRC> matches case-insensitively"
assert_extracts "$ert_root/single.md" "../images/shared.png|" "single-quoted src"
rm -rf "$ert_root"
# build_image_section runs the real image_section_json jq from
# docs-preview.yaml: combine the changed-image list and "<image>\t<page>"
# pairs into [{image, pages:[...]}], images sorted, pages per image deduped
# and sorted. An image with no pair keeps pages:[], so an icon- or
# screenshot-only PR still renders.
build_image_section() {
local images_list="$1" pairs_tsv="$2"
jq -n \
--argjson images "$(printf '%s\n' "$images_list" | jq -R -s '[splits("\n") | select(length > 0)]')" \
--argjson pairs "$(printf '%s\n' "$pairs_tsv" | jq -R -s '[splits("\n") | select(length > 0) | split("\t") | {image: .[0], page: .[1]}]')" \
'($pairs | group_by(.image) | map({key: .[0].image, value: (map(.page) | unique)}) | from_entries) as $by
| [$images[] | {image: ., pages: ($by[.] // [])}]
| sort_by(.image)'
}
# c.png is a changed image with no pair (the icon-only case); it must still
# appear, with pages: [].
images_list_fixture=$(printf 'docs/images/b.png\ndocs/images/a.png\ndocs/images/c.png')
pairs_fixture=$(printf 'docs/images/b.png\tdocs/z.md\ndocs/images/a.png\tdocs/p2.md\ndocs/images/a.png\tdocs/p1.md\ndocs/images/a.png\tdocs/p1.md')
actual_group=$(build_image_section "$images_list_fixture" "$pairs_fixture" | jq -c .)
expected_group='[{"image":"docs/images/a.png","pages":["docs/p1.md","docs/p2.md"]},{"image":"docs/images/b.png","pages":["docs/z.md"]},{"image":"docs/images/c.png","pages":[]}]'
if [ "$actual_group" = "$expected_group" ]; then
echo "PASS: build_image_section (sorted images, de-duped sorted pages, unmapped image kept with empty pages)"
else
echo "FAIL: build_image_section -> $actual_group (expected $expected_group)"
failures=$((failures + 1))
fi
# build_comment_body and render_image_section mirror the body assembler in
# docs-preview.yaml, rendering the exact comment body the workflow posts so
# it can be sized by measuring real bytes not estimating. Read the
# $final_rows, $total_pages, $url_prefix, $image_section, $image_section_json,
# $DOCS_PREVIEW_MARKER, $STATE_PREFIX, and IMAGE_* globals set before each
# case below. Keep in sync with docs-preview.yaml.
DOCS_PREVIEW_MARKER='<!-- docs-preview -->'
STATE_PREFIX='docs-preview-state:'
# Representative values for the Files-tab link in the omitted-pages
# summary; the workflow supplies these from the GitHub Actions env.
REPO='owner/repo'
PR_NUMBER='123'
# Caps that bound the image section, mirrored from docs-preview.yaml.
IMAGE_SECTION_BUDGET=20000
IMAGE_PAGES_MAX=25
# Default so the page-only cases below can call build_comment_body under
# set -u; the image cases set it via render_image_section.
image_section=""
# The per-commit preview list, mirrored from docs-preview.yaml. Empty by
# default so the cases that predate it render without the list.
COMMITS_MAX=100
commit_lines=""
commit_count=0
# merge_commit_lines mirrors docs-preview.yaml: this run's commit first, then
# the earlier commits' lines read back from the existing comment, minus a
# repeat of this commit, capped at COMMITS_MAX. Reads $SHORT_SHA, $PR_NUMBER
# and $domain.
merge_commit_lines() {
local body="$1" domain_re
domain_re=${domain//./\\.}
{
# shellcheck disable=SC2016 # backticks are literal Markdown code-span delimiters.
printf -- '- `%s` https://pr-%s-%s.%s\n' "$SHORT_SHA" "$PR_NUMBER" "$SHORT_SHA" "$domain"
printf '%s\n' "$body" | grep -E "^- \`[0-9a-f]{9}\` https://pr-${PR_NUMBER}-[0-9a-f]{9}\.${domain_re}\$" | grep -vF "\`${SHORT_SHA}\`" || true
} | awk -v max="$COMMITS_MAX" 'NR <= max'
}
page_url() {
local filename="$1" page_path url
page_path=$(map_doc_path "$filename")
url="$url_prefix"
if [ -n "$page_path" ]; then
url="${url}/${page_path}"
fi
printf '%s' "$url"
}
render_image_section() {
local budget="$1" count intro header out="" shown=0 i=0
local image page_count entry j page url dropped candidate
count=$(printf '%s' "$image_section_json" | jq 'length')
if [ "$count" -eq 0 ]; then
return 0
fi
intro="These images changed. Each is listed with the navigable page(s) that embed it, so you can open the preview and see the new image in context. An image with no page listed isn't embedded by any navigable docs page. These links are informational and have no review checkboxes."
header="#### Changed images"$'\n\n'"${intro}"$'\n\n'
while [ "$i" -lt "$count" ]; do
image=$(printf '%s' "$image_section_json" | jq -r --argjson i "$i" '.[$i].image')
page_count=$(printf '%s' "$image_section_json" | jq --argjson i "$i" '.[$i].pages | length')
# The backticks are literal Markdown code-span delimiters.
entry="- \`${image}\`"$'\n'
j=0
while [ "$j" -lt "$page_count" ] && [ "$j" -lt "$IMAGE_PAGES_MAX" ]; do
page=$(printf '%s' "$image_section_json" | jq -r --argjson i "$i" --argjson j "$j" '.[$i].pages[$j]')
url=$(page_url "$page")
entry="${entry} - [\`${page}\`](${url})"$'\n'
j=$((j + 1))
done
if [ "$page_count" -gt "$IMAGE_PAGES_MAX" ]; then
entry="${entry} - _and $((page_count - IMAGE_PAGES_MAX)) more page(s) embedding this image_"$'\n'
fi
# Keep the first image unconditionally (an empty section under a
# header is self-contradicting); measure each later image's
# would-be section and stop before it exceeds budget.
if [ "$shown" -gt 0 ]; then
candidate="${header}${out}${entry}"
if [ "$(printf '%s' "$candidate" | LC_ALL=C wc -c)" -gt "$budget" ]; then
break
fi
fi
out="${out}${entry}"
shown=$((shown + 1))
i=$((i + 1))
done
dropped=$((count - shown))
if [ "$dropped" -gt 0 ]; then
out="${out}"$'\n'"_and ${dropped} more changed image(s) not listed to stay under GitHub's comment size limit. See the [Files tab](https://github.com/${REPO}/pull/${PR_NUMBER}/files) for the full list._"$'\n'
fi
printf '%s%s' "$header" "$out"
}
build_comment_body() {
local n="$1" rows state_json state_b64 checklist="" intro page_block=""
local filename checked url box omitted
rows=$(printf '%s' "$final_rows" | jq -c --argjson n "$n" '.[:$n]')
state_json=$(printf '%s' "$rows" | jq -c 'map({(.filename): .sha}) | add // {}')
state_b64=$(printf '%s' "$state_json" | base64 -w0)
if [ "$total_pages" -gt 0 ]; then
while IFS=$'\t' read -r filename checked; do
[ -z "$filename" ] && continue
url=$(page_url "$filename")
box=" "
if [ "$checked" = "true" ]; then
box="x"
fi
# The backticks are literal Markdown code-span delimiters.
checklist="${checklist}- [${box}] [\`${filename}\`](${url})"$'\n'
done < <(printf '%s' "$rows" | jq -r '.[] | [.filename, (.checked | tostring)] | @tsv')
omitted=$((total_pages - n))
if [ "$omitted" -gt 0 ]; then
checklist="${checklist}"$'\n'"_and ${omitted} more changed page(s) not listed to stay under GitHub's comment size limit. See the [Files tab](https://github.com/${REPO}/pull/${PR_NUMBER}/files) for the full list._"$'\n'
fi
intro="Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here."
page_block="${intro}"$'\n\n'"${checklist}"
fi
# The identity and state markers are always present so the comment
# stays discoverable and round-trippable, even on an image-only PR
# whose state map is {}.
{
printf '## Docs preview\n\n'
# shellcheck disable=SC2016 # backticks are literal Markdown code-span delimiters.
printf 'Links open this pull request'"'"'s preview at %s, which updates with each push.\n\n' "$url_prefix"
if [ -n "$page_block" ]; then
printf '%s\n' "$page_block"
fi
if [ -n "$image_section" ]; then
printf '%s\n' "$image_section"
fi
if [ -n "$commit_lines" ]; then
printf '<details>\n<summary>Preview sites for each built commit (%s)</summary>\n\n' "$commit_count"
printf "Every built commit keeps its own preview, newest first. Previews aren't indexed by search engines and are deleted when this pull request is merged or closed.\n\n"
printf '%s\n\n</details>\n\n' "$commit_lines"
fi
printf '%s\n' "$DOCS_PREVIEW_MARKER"
printf '<!-- %s%s -->' "$STATE_PREFIX" "$state_b64"
}
}
# cap_pages mirrors the measure-and-binary-search cap in docs-preview.yaml:
# keep every page if the whole body fits, else the largest leading prefix
# whose rendered body stays under $budget.
cap_pages() {
local budget="$1" keep lo hi mid
if [ "$(build_comment_body "$total_pages" | LC_ALL=C wc -c)" -le "$budget" ]; then
printf '%s' "$total_pages"
return
fi
lo=0
hi=$((total_pages - 1))
keep=0
while [ "$lo" -le "$hi" ]; do
mid=$(((lo + hi) / 2))
if [ "$(build_comment_body "$mid" | LC_ALL=C wc -c)" -le "$budget" ]; then
keep=$mid
lo=$((mid + 1))
else
hi=$((mid - 1))
fi
done
printf '%s' "$keep"
}
budget=65000
# GitHub's hard comment-body limit; the budget above leaves headroom under it.
github_comment_limit=65536
# Repo-scale worst case: a 400-page docs migration on a long branch with
# ~60-char paths. The cap must keep the real body under GitHub's 65536-char
# limit while still listing as many pages as fit.
url_prefix="https://pr-123456.docs.cdr-preview.dev"
final_rows=$(jq -nc '[range(400) | {
filename: ("docs/reference/generated/section-\(. + 1000)/really-long-page-name-\(. + 1000).md"),
sha: ("0123456789abcdef0123456789abcdef" + (. + 100000 | tostring)),
checked: false
}]')
total_pages=$(printf '%s' "$final_rows" | jq 'length')
keep=$(cap_pages "$budget")
final_body_bytes=$(build_comment_body "$keep" | LC_ALL=C wc -c)
if [ "$keep" -lt "$total_pages" ] && [ "$final_body_bytes" -le "$github_comment_limit" ]; then
echo "PASS: repo-scale cap keeps $keep/$total_pages pages, body ${final_body_bytes}B <= ${github_comment_limit}"
else
echo "FAIL: repo-scale cap keeps $keep/$total_pages pages, body ${final_body_bytes}B (want < total and <= ${github_comment_limit})"
failures=$((failures + 1))
fi
# Tightness: one page past the cap must exceed the budget, proving the
# cap doesn't leave usable space on the table.
over_body_bytes=$(build_comment_body "$((keep + 1))" | LC_ALL=C wc -c)
if [ "$over_body_bytes" -gt "$budget" ]; then
echo "PASS: cap is tight (keep+1 body ${over_body_bytes}B > ${budget})"
else
echo "FAIL: cap is not tight (keep+1 body ${over_body_bytes}B <= ${budget})"
failures=$((failures + 1))
fi
# A small PR keeps every page and renders no omitted-pages summary line.
url_prefix="https://pr-1.docs.cdr-preview.dev"
final_rows=$(jq -nc '[range(5) | {filename: ("docs/page-\(.).md"), sha: "abc", checked: false}]')
total_pages=$(printf '%s' "$final_rows" | jq 'length')
keep=$(cap_pages "$budget")
small_body=$(build_comment_body "$keep")
if [ "$keep" -eq 5 ] && ! printf '%s' "$small_body" | grep -q "more changed page"; then
echo "PASS: small PR keeps all 5 pages with no summary line"
else
echo "FAIL: small PR keep=$keep (expected 5) or unexpected summary line"
failures=$((failures + 1))
fi
# Round-trip build_comment_body's *own emitted* marker back through
# recover_old_state, proving the producer and consumer marker formats agree
# (a drift would silently reset every checkbox on every push).
emitted_state=$(recover_old_state "$small_body")
expected_state=$(printf '%s' "$final_rows" | jq -c 'map({(.filename): .sha}) | add // {}')
if [ "$emitted_state" = "$expected_state" ]; then
echo "PASS: emitted marker round-trips through recovery"
else
echo "FAIL: emitted marker round-trip -> $emitted_state (expected $expected_state)"
failures=$((failures + 1))
fi
# render_image_section renders a nested list of each changed image with a
# preview link for every page that embeds it. A docs-root page
# (docs/README.md) links to the branch root with no trailing path.
url_prefix="https://pr-1.docs.cdr-preview.dev"
IMAGE_PAGES_MAX=25
image_section_json='[{"image":"docs/images/a.png","pages":["docs/user-guides/x.md","docs/y.md"]},{"image":"docs/images/b.png","pages":["docs/README.md"]}]'
section=$(render_image_section "$IMAGE_SECTION_BUDGET")
# shellcheck disable=SC2016 # backtick-quoted paths are literal Markdown.
if printf '%s' "$section" | grep -qF '#### Changed images' &&
printf '%s' "$section" | grep -qF -- '- `docs/images/a.png`' &&
printf '%s' "$section" | grep -qF -- ' - [`docs/user-guides/x.md`](https://pr-1.docs.cdr-preview.dev/user-guides/x)' &&
printf '%s' "$section" | grep -qF -- ' - [`docs/README.md`](https://pr-1.docs.cdr-preview.dev)'; then
echo "PASS: render_image_section (nested preview links; README maps to docs root)"
else
echo "FAIL: render_image_section basic ->"
printf '%s\n' "$section"
failures=$((failures + 1))
fi
# Per-image page cap: at most IMAGE_PAGES_MAX links, then an "and N more"
# note. Page-link lines start with two spaces, a dash and a bracket; the
# note line starts with an underscore, so ^ - \[ counts only the links.
IMAGE_PAGES_MAX=2
many_pages=$(jq -nc '[range(5) | "docs/p\(.).md"]')
image_section_json=$(jq -nc --argjson p "$many_pages" '[{image: "docs/images/big.png", pages: $p}]')
section=$(render_image_section "$IMAGE_SECTION_BUDGET")
shown_links=$(printf '%s\n' "$section" | grep -cE '^ - \[')
if [ "$shown_links" -eq 2 ] && printf '%s' "$section" | grep -qF 'and 3 more page(s) embedding this image'; then
echo "PASS: render_image_section (per-image page cap keeps 2 with an overflow note)"
else
echo "FAIL: render_image_section page cap -> shown_links=$shown_links"
printf '%s\n' "$section"
failures=$((failures + 1))
fi
IMAGE_PAGES_MAX=25
# Byte-budget truncation across images: with a 1-byte budget only the
# first image (always kept) renders, and a trailing "and N more image(s)"
# note reports the rest.
image_section_json='[{"image":"docs/images/aaaaaaaaaa.png","pages":["docs/one.md"]},{"image":"docs/images/bbbbbbbbbb.png","pages":["docs/two.md"]},{"image":"docs/images/cccccccccc.png","pages":["docs/three.md"]}]'
section=$(render_image_section 1)
# shellcheck disable=SC2016 # backtick is a literal Markdown delimiter.
imgs_shown=$(printf '%s\n' "$section" | grep -cE '^- `docs/images/')
if [ "$imgs_shown" -eq 1 ] && printf '%s' "$section" | grep -qF 'and 2 more changed image(s) not listed'; then
echo "PASS: render_image_section (byte-budget truncation keeps first image + note)"
else
echo "FAIL: render_image_section truncation -> imgs_shown=$imgs_shown"
printf '%s\n' "$section"
failures=$((failures + 1))
fi
# build_comment_body on an image-only PR (zero changed pages): the
# checklist and its intro are omitted, the image section renders, both
# hidden markers are present, and the state map is {}.
final_rows='[]'
total_pages=0
url_prefix="https://pr-1.docs.cdr-preview.dev"
image_section_json='[{"image":"docs/images/a.png","pages":["docs/user-guides/x.md"]}]'
image_section=$(render_image_section "$IMAGE_SECTION_BUDGET")
image_only_body=$(build_comment_body 0)
if printf '%s' "$image_only_body" | grep -qF '#### Changed images' &&
! printf '%s' "$image_only_body" | grep -qF 'Check off each page' &&
printf '%s' "$image_only_body" | grep -qF 'These links are informational and have no review checkboxes.' &&
! printf '%s' "$image_only_body" | grep -qF 'separate from the checklist above' &&
printf '%s' "$image_only_body" | grep -qF '<!-- docs-preview -->' &&
[ "$(recover_old_state "$image_only_body")" = '{}' ]; then
echo "PASS: build_comment_body (image-only PR: image section, no checklist, empty state)"
else
echo "FAIL: build_comment_body image-only ->"
printf '%s\n' "$image_only_body"
failures=$((failures + 1))
fi
# Icon-only PR: the only changed image embeds no navigable page, so
# image_section_json carries it with pages:[]. The comment must still render,
# listing the image on its own line with no sub-links.
final_rows='[]'
total_pages=0
url_prefix="https://pr-1.docs.cdr-preview.dev"
image_section_json='[{"image":"docs/images/icons/system.svg","pages":[]}]'
image_section=$(render_image_section "$IMAGE_SECTION_BUDGET")
icon_only_body=$(build_comment_body 0)
# shellcheck disable=SC2016 # backtick-quoted path is literal Markdown.
if printf '%s' "$icon_only_body" | grep -qF '#### Changed images' &&
printf '%s' "$icon_only_body" | grep -qF -- '- `docs/images/icons/system.svg`' &&
! printf '%s' "$icon_only_body" | grep -qF 'Check off each page' &&
[ "$(printf '%s\n' "$icon_only_body" | grep -cE '^ - \[')" -eq 0 ]; then
echo "PASS: build_comment_body (icon-only PR: unmapped image still produces a comment)"
else
echo "FAIL: build_comment_body icon-only ->"
printf '%s\n' "$icon_only_body"
failures=$((failures + 1))
fi
# build_comment_body with both changed pages and images: both sections
# render. A page that is both changed and an image referrer appears in both,
# and the image sub-link (no checkbox glyph) never pollutes carried-over
# checkbox state.
final_rows='[{"filename":"docs/a.md","sha":"s1","checked":true},{"filename":"docs/b.md","sha":"s2","checked":false}]'
total_pages=2
image_section_json='[{"image":"docs/images/a.png","pages":["docs/a.md"]}]'
image_section=$(render_image_section "$IMAGE_SECTION_BUDGET")
both_body=$(build_comment_body 2)
# shellcheck disable=SC2016 # backtick-quoted paths are literal Markdown.
if printf '%s' "$both_body" | grep -qF 'Check off each page' &&
printf '%s' "$both_body" | grep -qF -- '- [x] [`docs/a.md`]' &&
printf '%s' "$both_body" | grep -qF '#### Changed images' &&
printf '%s' "$both_body" | grep -qF -- ' - [`docs/a.md`](https://pr-1.docs.cdr-preview.dev/a)'; then
echo "PASS: build_comment_body (pages and images both render)"
else
echo "FAIL: build_comment_body pages+images ->"
printf '%s\n' "$both_body"
failures=$((failures + 1))
fi
if [ "$(recover_old_checked "$both_body" | jq -cS .)" = '{"docs/a.md":true,"docs/b.md":false}' ]; then
echo "PASS: build_comment_body (image sub-links excluded from checkbox state)"
else
echo "FAIL: image sub-links polluted checkbox state -> $(recover_old_checked "$both_body")"
failures=$((failures + 1))
fi
# The per-commit preview list: this run's commit first, then the earlier
# commits read back from the existing comment, minus a repeat of this commit
# and any line for another PR or domain.
PR_NUMBER='123'
domain='docs.cdr-preview.dev'
SHORT_SHA='ccccccccc'
# shellcheck disable=SC2016 # backtick-quoted SHAs are literal Markdown.
existing_commits_body=$(printf '%s\n' \
'## Docs preview' \
'- `bbbbbbbbb` https://pr-123-bbbbbbbbb.docs.cdr-preview.dev' \
'- `ccccccccc` https://pr-123-ccccccccc.docs.cdr-preview.dev' \
'- `aaaaaaaaa` https://pr-123-aaaaaaaaa.docs.cdr-preview.dev' \
'- `ddddddddd` https://pr-999-ddddddddd.docs.cdr-preview.dev' \
'- `eeeeeeeee` https://pr-123-eeeeeeeee.coderite.app')
merged=$(merge_commit_lines "$existing_commits_body")
# shellcheck disable=SC2016 # backtick-quoted SHAs are literal Markdown.
expected_merged=$(printf '%s\n' \
'- `ccccccccc` https://pr-123-ccccccccc.docs.cdr-preview.dev' \
'- `bbbbbbbbb` https://pr-123-bbbbbbbbb.docs.cdr-preview.dev' \
'- `aaaaaaaaa` https://pr-123-aaaaaaaaa.docs.cdr-preview.dev')
if [ "$merged" = "$expected_merged" ]; then
echo "PASS: merge_commit_lines (this commit first, earlier ones kept, repeats and other PRs dropped)"
else
echo "FAIL: merge_commit_lines ->"
printf '%s\n' "$merged"
failures=$((failures + 1))
fi
# The list stops at COMMITS_MAX lines, keeping the newest.
# shellcheck disable=SC2016 # backticks are literal Markdown code-span delimiters.
long_commits_body=$(for i in $(seq 1 150); do printf -- '- `%09x` https://pr-123-%09x.docs.cdr-preview.dev\n' "$i" "$i"; done)
capped=$(merge_commit_lines "$long_commits_body")
# shellcheck disable=SC2016 # backticks are literal Markdown code-span delimiters.
if [ "$(printf '%s\n' "$capped" | wc -l | tr -d ' ')" -eq 100 ] && [ "$(printf '%s\n' "$capped" | head -n 1)" = '- `ccccccccc` https://pr-123-ccccccccc.docs.cdr-preview.dev' ]; then
echo "PASS: merge_commit_lines (capped at 100, newest first)"
else
echo "FAIL: merge_commit_lines cap -> $(printf '%s\n' "$capped" | wc -l) lines"
failures=$((failures + 1))
fi
# The list renders in a collapsible block, reads back from the comment the
# workflow itself posted, and never counts as checkbox state.
final_rows='[{"filename":"docs/a.md","sha":"s1","checked":true}]'
total_pages=1
image_section=""
url_prefix="https://pr-123.docs.cdr-preview.dev"
commit_lines="$expected_merged"
commit_count=3
commits_body=$(build_comment_body 1)
if printf '%s' "$commits_body" | grep -qxF '<details>' &&
printf '%s' "$commits_body" | grep -qxF '<summary>Preview sites for each built commit (3)</summary>' &&
printf '%s' "$commits_body" | grep -qxF '</details>' &&
[ "$(SHORT_SHA='fffffffff' merge_commit_lines "$commits_body" | tail -n +2)" = "$expected_merged" ] &&
[ "$(recover_old_checked "$commits_body" | jq -c .)" = '{"docs/a.md":true}' ]; then
echo "PASS: build_comment_body (collapsible preview list round-trips; no checkbox pollution)"
else
echo "FAIL: build_comment_body preview list ->"
printf '%s\n' "$commits_body"
failures=$((failures + 1))
fi
commit_lines=""
commit_count=0
# One comment per PR: the deploy job posts nothing itself and hands its commit
# to docs-preview.yaml, which posts only when a non-generated page or image
# changed.
deploy_job=$(awk '/^ deploy:/{on=1} /^ comment:/{on=0} on' "$(dirname "${BASH_SOURCE[0]}")/docs-pr-preview-deploy.yaml")
# shellcheck disable=SC2016 # the expected lines are literal workflow text.
if ! grep -qF '/comments' <<<"$deploy_job" &&
! grep -qF 'pull-requests: write' <<<"$deploy_job" &&
grep -qF 'short_sha: ${{ needs.deploy.outputs.short_sha }}' "$(dirname "${BASH_SOURCE[0]}")/docs-pr-preview-deploy.yaml" &&
grep -qE '^ short_sha:' "$(dirname "${BASH_SOURCE[0]}")/docs-preview.yaml"; then
echo "PASS: the deploy job posts no comment and passes its commit to docs-preview.yaml"
else
echo "FAIL: the deploy job still posts its own preview comment"
failures=$((failures + 1))
fi
# Preview links go to the PR's own preview on the preview-only domain in the
# DOCS_PREVIEW_DOMAIN variable (docs.cdr-preview.dev), which
# docs-pr-preview-deploy.yaml aliases on every build: never to a coder.com
# branch path or a first-come vercel.app name. The link uses the domain only
# after the workflow has validated it.
workflow="$(dirname "${BASH_SOURCE[0]}")/docs-preview.yaml"
# shellcheck disable=SC2016 # the expected lines are literal workflow text.
if grep -qF 'DOCS_PREVIEW_DOMAIN: ${{ vars.DOCS_PREVIEW_DOMAIN }}' "$workflow" &&
grep -qF 'url_prefix="https://pr-${PR_NUMBER}.${domain}"' "$workflow" &&
! grep -qF 'coder.com/docs/@' "$workflow" &&
! grep -qE 'https://[^"[:space:]]*vercel\.app' "$workflow"; then
echo "PASS: preview links use pr-<n>.\$DOCS_PREVIEW_DOMAIN"
else
echo "FAIL: docs-preview.yaml does not build preview links on pr-<n>.\$DOCS_PREVIEW_DOMAIN"
failures=$((failures + 1))
fi
# The comment links to a preview only once one exists: docs-preview.yaml
# runs only when docs-pr-preview-deploy.yaml calls it after a deploy.
deploy_workflow="$(dirname "${BASH_SOURCE[0]}")/docs-pr-preview-deploy.yaml"
if grep -qE '^ workflow_call:' "$workflow" &&
! grep -qE '^ pull_request(_target)?:' "$workflow" &&
grep -qF 'uses: ./.github/workflows/docs-preview.yaml' "$deploy_workflow" &&
grep -qE '^ needs: \[?deploy' "$deploy_workflow"; then
echo "PASS: docs-preview comment runs only after a successful deploy"
else
echo "FAIL: docs-preview.yaml can post preview links before a deploy succeeds"
failures=$((failures + 1))
fi
# The PR picks the engine commit through docs/.engine-ref. Once docs-engine is
# public, a commit pushed to any fork of it can be fetched by SHA through
# coder/docs-engine, so the engine job builds only commits on docs-engine main:
# it checks out full history and fails before packing unless the pin is an
# ancestor of origin/main.
engine_job=$(awk '/^ engine:/{on=1} /^ build:/{on=0} on' "$deploy_workflow")
# shellcheck disable=SC2016 # the expected lines are literal workflow text.
if grep -qF 'fetch-depth: 0' <<<"$engine_job" &&
grep -qF 'git -C engine merge-base --is-ancestor "$REF" origin/main' <<<"$engine_job" &&
awk '/merge-base --is-ancestor/{seen=1} /name: Pack the engine source/{exit !seen}' <<<"$engine_job"; then
echo "PASS: the engine job builds only commits on docs-engine main"
else
echo "FAIL: docs/.engine-ref can pin a docs-engine commit that is not on main"
failures=$((failures + 1))
fi
if [ "$failures" -gt 0 ]; then
echo ""
echo "$failures test(s) failed."
exit 1
fi
echo ""
echo "All tests passed."