From 352b5262da32d23bbac200defe167891d57f4c21 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 21 Feb 2026 15:08:24 +0100
Subject: [PATCH] fix(ci): make docs spellcheck fallback deterministic

---
 package.json                 |  4 ++--
 scripts/codespell-ignore.txt |  7 ++++++
 scripts/docs-spellcheck.sh   | 44 ++++++++++++++++++++++++++++++++++++
 3 files changed, 53 insertions(+), 2 deletions(-)
 create mode 100644 scripts/docs-spellcheck.sh

diff --git a/package.json b/package.json
index 43bd5bf111c..ab26f4ea23e 100644
--- a/package.json
+++ b/package.json
@@ -70,8 +70,8 @@
     "docs:check-links": "node scripts/docs-link-audit.mjs",
     "docs:dev": "cd docs && mint dev",
     "docs:list": "node scripts/docs-list.js",
-    "docs:spellcheck": "if command -v codespell >/dev/null 2>&1; then codespell README.md docs --skip='*.png,*.jpg,*.jpeg,*.gif,*.svg' -D - -D scripts/codespell-dictionary.txt -I scripts/codespell-ignore.txt; else pnpm dlx codespell README.md docs --skip='*.png,*.jpg,*.jpeg,*.gif,*.svg' -D - -D scripts/codespell-dictionary.txt -I scripts/codespell-ignore.txt; fi",
-    "docs:spellcheck:fix": "if command -v codespell >/dev/null 2>&1; then codespell README.md docs --skip='*.png,*.jpg,*.jpeg,*.gif,*.svg' -D - -D scripts/codespell-dictionary.txt -I scripts/codespell-ignore.txt -w; else pnpm dlx codespell README.md docs --skip='*.png,*.jpg,*.jpeg,*.gif,*.svg' -D - -D scripts/codespell-dictionary.txt -I scripts/codespell-ignore.txt -w; fi",
+    "docs:spellcheck": "bash scripts/docs-spellcheck.sh",
+    "docs:spellcheck:fix": "bash scripts/docs-spellcheck.sh --write",
     "format": "oxfmt --write",
     "format:all": "pnpm format && pnpm format:swift",
     "format:check": "oxfmt --check",
diff --git a/scripts/codespell-ignore.txt b/scripts/codespell-ignore.txt
index b7008d3eabf..3c242f6a2e2 100644
--- a/scripts/codespell-ignore.txt
+++ b/scripts/codespell-ignore.txt
@@ -1,2 +1,9 @@
 iTerm
 FO
+Nam
+Lins
+Vai
+OptionA
+CAF
+overlayed
+re-use
diff --git a/scripts/docs-spellcheck.sh b/scripts/docs-spellcheck.sh
new file mode 100644
index 00000000000..17505993dbc
--- /dev/null
+++ b/scripts/docs-spellcheck.sh
@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+mode="${1:-}"
+write_flag=()
+if [[ "$mode" == "--write" ]]; then
+  write_flag=(-w)
+fi
+
+args=(
+  README.md
+  docs
+  --skip=*.png,*.jpg,*.jpeg,*.gif,*.svg
+  -D
+  -
+  -D
+  scripts/codespell-dictionary.txt
+  -I
+  scripts/codespell-ignore.txt
+  "${write_flag[@]}"
+)
+
+if command -v codespell >/dev/null 2>&1; then
+  codespell "${args[@]}"
+  exit 0
+fi
+
+if command -v python3 >/dev/null 2>&1; then
+  python3 -m pip install --user --disable-pip-version-check --break-system-packages codespell >/dev/null 2>&1 || \
+    python3 -m pip install --user --disable-pip-version-check codespell >/dev/null 2>&1
+
+  user_bin="$(python3 - <<'PY'
+import site
+print(f"{site.USER_BASE}/bin")
+PY
+)"
+  if [[ -x "${user_bin}/codespell" ]]; then
+    "${user_bin}/codespell" "${args[@]}"
+    exit 0
+  fi
+fi
+
+echo "codespell unavailable: install codespell or python3" >&2
+exit 1