Fix the Vale flag, project encoding, and overwrite in the docs gate

Andrew Dunnrequested to merge
fix/docs-gate-vale-encoding-overwrite into main

Closes #5 (closed)

This fixes three defects in the docs gate, one commit each. Each commit carries a test in tests/run.sh.

docs-lint: Pass --no-color only to a Vale that has it

Vale 3.14.1 has no --no-color flag. Given it, Vale prints its usage and exits 0 without a summary, so the gate failed closed and could not run on any target or MR head that pins that version. The flag now goes only to a Vale whose --help lists it. Nothing keys on a version number.

docs-lint: Encode --project exactly once, and docs-mr too

docs-lint.sh encoded an already-encoded path again (gitlab-org%252Fgitlab), and every fetch 404'd. docs-mr.sh put a plain path into its URLs unencoded. Both now decode, then encode once. The docs-lint 404 fix in !14 (merged) (56a1158b) covered a missing mise.toml, a different defect.

docs-mr: Refuse to overwrite a page that moved since its fetch

docs-mr.sh sent no last_commit_id, so a page that changed on the target between the fetch and the commit was overwritten silently. --file now needs --base, the full SHA from docs-mr.md step 1. Each update carries the page's last commit read at that SHA, so the guard comes from the snapshot the edit was made against, not from a fresh read at the head. GitLab answers a stale value with a 400 and writes nothing (measured on this project: no branch created), and the script exits 1 with no MR. The pre-write lint runs at --base too.

Verification

  • just ci passes: 135 assertions, shellcheck clean.
  • The branch's run.sh against main's scripts fails 12 assertions, 8 of them new. The other 4 existing docs-mr assertions now pass --base, which main rejects. The fix-3 assertion that fails for the defect itself, rather than the missing flag, is "an update with no --base is refused before any write": main sent an unguarded update to a moved page and exited 0.
  • Live, read-only, against gitlab-org/gitlab-runner docs/_index.md with the real Vale 3.14.1 forced: main fails with "Vale printed no summary line" on a plain path, and with "fetch FAILED: projects/gitlab-org%252Fgitlab-runner" on an encoded one. The branch passes with the encoded path.

Merge request reports