#!/bin/bash

# Regression tests for the path-mapping logic in docs-preview.yaml.

# The mapper converts a repo-relative docs path into the URL path

# used by the docs site preview. Five distinct branches exist in the

# case block; every branch must be covered here.

#

# Also covers the other logic-dense pieces of docs-preview.yaml:

# extracting page paths from docs/manifest.json, filtering the PR's

# changed files, intersecting the two into the eligible set, parsing

# checkbox state out of the rendered checklist, and the checked-state

# carryover. Where the workflow runs jq, these tests run the same jq

# against fixtures rather than a shell mirror. Keep them 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/about/contributing/CONTRIBUTING.md" "about/contributing/CONTRIBUTING"

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 `jq -r '[.. | objects | select(has("path")) | .path]'`

# output. manifest.json paths are written either "./foo/bar.md" or

# "foo/bar.md" relative to docs/; both forms must normalize to the

# same "docs/foo/bar.md" so they compare directly against the

# filenames returned by the PR-files API.

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 existing comment body to recover the *live* checked

# state a reviewer's clicks land in (GitHub persists a checkbox toggle

# as a comment-body edit). Emits "<x-or-space>\t<path>", matching the

# workflow's intermediate TSV format.

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://coder.com/docs/@b/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://coder.com/docs/@b/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://coder.com/docs/@b/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' ""

# decide_checked removed: round_trip_state below covers the carryover

# rule through the workflow's real jq, so the hand-written shell mirror

# only added a green check that guarded nothing.

# round_trip_state exercises the *actual* jq/grep/sed/base64 expressions

# from docs-preview.yaml end to end, which a hand-written shell mirror of

# the carryover rule could not: it drives the jq null-coalescing

# (// false, // null) and the base64 state marker directly. A path->sha

# map is encoded into the hidden marker, read back, the live checkbox

# glyphs are parsed, and the carryover jq decides each page's final

# checked state.

STATE_PREFIX='docs-preview-state:'

# Recovers the {path: sha} state map from the hidden marker, a faithful

# copy of the guarded block in docs-preview.yaml: decode under

# `2>/dev/null || true` and adopt the result only if it is non-empty and

# parses as a JSON object, else degrade to {} so a corrupt marker can't

# kill the run. The non-empty check keeps the guard's 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://coder.com/docs/@b/a)' \

'- [ ] [`docs/b.md`](https://coder.com/docs/@b/b)' \

'- [x] [`docs/c.md`](https://coder.com/docs/@b/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

# The malformed-marker path the decode guard added 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, emitting one

# normalized repo-relative path per line. Guards the recursive

# `[.. | objects | select(has("path")) | .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) | [.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"}

]'

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/non-md/non-docs excluded)"

else

echo "FAIL: filter_changed_files -> \"$actual_changed\" (expected \"$expected_changed\")"

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. This is the single decision the feature exists to

# make, so cover it directly.

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

# build_comment_body mirrors the body assembler in docs-preview.yaml:

# it renders the first N pages of $final_rows into the exact

# comment body the workflow posts, so the comment can be sized by

# measuring the real bytes instead of estimating a per-page cost. Reads

# the $final_rows, $total_pages, $url_prefix, $DOCS_PREVIEW_MARKER, and

# $STATE_PREFIX 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'

build_comment_body() {

local n="$1" rows state_json state_b64 checklist="" intro

local filename checked page_path 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)

while IFS=$'\t' read -r filename checked; do

[ -z "$filename" ] && continue

page_path=$(map_doc_path "$filename")

url="$url_prefix"

if [ -n "$page_path" ]; then

url="${url}/${page_path}"

fi

box=" "

if [ "$checked" = "true" ]; then

box="x"

fi

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

printf '## Docs preview\n\n%s\n\n%s\n%s\n<!-- %s%s -->' \

"$intro" "$checklist" "$DOCS_PREVIEW_MARKER" "$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 docs migration touching 400 pages on a long

# ticket-prefixed branch, ~60-char paths, the shape reviewers measured

# overflowing the old per-page estimate. The cap must keep the real body

# under GitHub's 65536-char limit while still listing as many pages as fit.

url_prefix="https://coder.com/docs/@feature-team-very-long-branch-name-docs-migration-2024"

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://coder.com/docs/@short-branch"

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

if [ "$failures" -gt 0 ]; then

echo ""

echo "$failures test(s) failed."

exit 1

fi

echo ""

echo "All tests passed."