ci: check docs.json redirects that cannot work

.github/workflows/docs-validation.yml

@@ -11,6 +11,9 @@ on:
       - main
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 # Pinned deliberately. `npx mintlify` resolves the `latest` dist-tag at run time, so a
 # broken upstream publish takes every PR in this repo red at once with a failure that has
 # nothing to do with the diff. That happened on 4.2.931, which carries a transitive
@@ -44,3 +47,11 @@ jobs:
 
       - name: Check for orphan pages
         run: bash scripts/check-orphans.sh
+
+      - name: Test the redirect check
+        run: python3 -m unittest discover -s scripts -p 'test_*.py'
+
+      # Catches redirects Mintlify accepts but that cannot work: wildcards shadowed by an
+      # earlier wildcard, chains, `#` in a source, sources that capture navigation paths.
+      - name: Check redirects
+        run: python3 scripts/check_redirects.py

AGENTS.md

@@ -20,17 +20,18 @@ Structural work in progress is tracked in the restructure epic, [#2266](https://
 npm i -g mint          # once
 mint dev               # preview at http://localhost:3000
 mint broken-links      # must pass before every PR; CI runs it on every PR to main
+python3 scripts/check_redirects.py  # must pass too when you touch redirects; CI runs it
 mint update            # if the CLI misbehaves
 ```
 
 ## 2. Before you move, rename or delete a page
 
 All four steps, every time. External links and search results break silently when one is skipped.
 
-1. Add a `redirects` entry in `docs.json`: `{ "source": "/old/path", "destination": "/new/path" }` — no `.mdx`, root-relative. Point at the final page, not at another redirect.
+1. Add a `redirects` entry in `docs.json`: `{ "source": "/old/path", "destination": "/new/path" }` — no `.mdx`, root-relative. Point at the final page, not at another redirect. A source cannot contain `#`: browsers never send the fragment, so it never matches. Write wildcards as a trailing `/:slug*`; the redirect check refuses any other path parameter. Between `:slug*` wildcards the first match wins, so put a narrower wildcard above a broader one.
 2. Update the page's entry under `navigation` (or remove it).
 3. Update every inbound internal link: `grep -rn --include='*.mdx' "/old/path" .`
-4. Run `mint broken-links`.
+4. Run `mint broken-links` and `python3 scripts/check_redirects.py`.
 
 Deleting a page still needs step 1 — redirect to the nearest page that answers the same question.
 

docs.json

@@ -542,7 +542,7 @@
       "anchors": [
         {
           "anchor": "Docs for AI",
-          "href": "/build-on-celo/build-with-ai/use-docs-with-ai",
+          "href": "/build/agents/use-docs-with-ai",
           "icon": "robot"
         },
         {
@@ -1327,10 +1327,6 @@
       "source": "/celo-codebase/protocol/identity/valora-accounts",
       "destination": "/learn/celo-l1"
     },
-    {
-      "source": "/celo-codebase/protocol/identity#using-the-mapping-for-payment",
-      "destination": "/build/build-on-socialconnect"
-    },
     {
       "source": "/celo-codebase/protocol/index",
       "destination": "/learn/protocol"
@@ -1411,30 +1407,14 @@
       "source": "/celo-codebase/protocol/proof-of-stake/epoch-rewards/community-fund",
       "destination": "/learn/protocol/epoch-rewards/community-fund"
     },
-    {
-      "source": "/celo-codebase/protocol/proof-of-stake/epoch-rewards/community-fund#bolstering-the-reserve",
-      "destination": "/learn/protocol/epoch-rewards/community-fund"
-    },
     {
       "source": "/celo-codebase/protocol/proof-of-stake/epoch-rewards/locked-gold-rewards",
       "destination": "/learn/protocol/epoch-rewards/index"
     },
-    {
-      "source": "/celo-codebase/protocol/proof-of-stake/epoch-rewards/locked-gold-rewards#introduction-to-locked-celo-rewards",
-      "destination": "/learn/protocol/epoch-rewards/index"
-    },
     {
       "source": "/celo-codebase/protocol/proof-of-stake/epoch-rewards/validator-rewards",
       "destination": "/learn/protocol/epoch-rewards/index"
     },
-    {
-      "source": "/celo-codebase/protocol/proof-of-stake/epoch-rewards/validator-rewards#:~:text=Calculating%20Uptime%20Score,validators%20committing%20the%20previous%20block.",
-      "destination": "/learn/protocol/epoch-rewards/index"
-    },
-    {
-      "source": "/celo-codebase/protocol/proof-of-stake/epoch-rewards/validator-rewards#calculating-uptime-score",
-      "destination": "/learn/protocol/epoch-rewards/index"
-    },
     {
       "source": "/celo-codebase/protocol/proof-of-stake/index",
       "destination": "/learn/protocol/staking/index"
@@ -1495,10 +1475,6 @@
       "source": "/celo-codebase/protocol/stability/stability-fees",
       "destination": "/learn/celo-l1"
     },
-    {
-      "source": "/celo-codebase/protocol/stability#stability-of-celos-stablecoin-protocol",
-      "destination": "/build/build-with-local-stablecoin"
-    },
     {
       "source": "/celo-codebase/protocol/transactions/erc20-transaction-fees",
       "destination": "/build/fee-abstraction/overview"
@@ -1559,10 +1535,6 @@
       "source": "/celo-gold-holder-guide/ledger",
       "destination": "/build/tools/wallets/ledger/setup"
     },
-    {
-      "source": "/celo-gold-holder-guide/ledger#install-the-celo-cli",
-      "destination": "/build/tools/wallets/ledger/to-celo-cli"
-    },
     {
       "source": "/celo-gold-holder-guide/quick-start",
       "destination": "/learn/manage/self-custody"
@@ -1655,14 +1627,6 @@
       "source": "/celo-owner-guide/quick-start",
       "destination": "/learn/manage/self-custody"
     },
-    {
-      "source": "/celo-owner-guide/quick-start#lock-celo",
-      "destination": "/learn/manage/self-custody"
-    },
-    {
-      "source": "/celo-owner-guide/quick-start#vote-for-a-validator-group",
-      "destination": "/learn/protocol/staking/voting"
-    },
     {
       "source": "/celo-owner-guide/release-gold",
       "destination": "/learn/manage/release-gold"
@@ -1795,10 +1759,6 @@
       "source": "/command-line-interface/commands",
       "destination": "/build/tools/libraries-sdks/cli/commands"
     },
-    {
-      "source": "/command-line-interface/commands/account#celocli-account-new",
-      "destination": "/build/tools/libraries-sdks/cli/account"
-    },
     {
       "source": "/command-line-interface/commands/exchange",
       "destination": "/build/tools/libraries-sdks/cli"
@@ -2359,14 +2319,6 @@
       "source": "/faqs",
       "destination": "/learn"
     },
-    {
-      "source": "/faqs#what-is-celos-supply",
-      "destination": "/learn"
-    },
-    {
-      "source": "/faqs#who-are-the-founders-of-celo",
-      "destination": "/learn/index"
-    },
     {
       "source": "/general",
       "destination": "/learn/index"
@@ -2527,42 +2479,10 @@
       "source": "/getting-started/wallets/using-metamask-with-celo/manual-setup",
       "destination": "/build/tools/wallets/metamask/use"
     },
-    {
-      "source": "/getting-started/wallets/using-metamask-with-celo/manual-setup#adding-a-celo-network-to-metamask",
-      "destination": "/build/tools/wallets/metamask/use"
-    },
-    {
-      "source": "/getting-started/wallets/using-metamask-with-celo/manual-setup#adding-tokens-eg-cusd-ceur",
-      "destination": "/build/tools/wallets/metamask/use"
-    },
-    {
-      "source": "/getting-started/wallets/using-metamask-with-celo/manual-setup#sending-assets-to-metamask",
-      "destination": "/build/tools/wallets/metamask/use"
-    },
-    {
-      "source": "/getting-started/wallets/using-metamask-with-celo/manual-setup#setup",
-      "destination": "/build/tools/wallets/metamask/use"
-    },
     {
       "source": "/getting-started/wallets/using-metamask-with-celo/using-a-ledger-with-metamask",
       "destination": "/build/tools/wallets/ledger/setup"
     },
-    {
-      "source": "/getting-started/wallets/using-metamask-with-celo#importing-via-private-key",
-      "destination": "/build/tools/wallets/metamask/import"
-    },
-    {
-      "source": "/getting-started/wallets#celo-compatible-wallets",
-      "destination": "/learn/wallets"
-    },
-    {
-      "source": "/getting-started/wallets#celo-native-wallets",
-      "destination": "/learn/wallets"
-    },
-    {
-      "source": "/getting-started/wallets#celowalletapp",
-      "destination": "/learn/wallets"
-    },
     {
       "source": "/holder/asset",
       "destination": "/learn/manage/asset"
@@ -2595,14 +2515,6 @@
       "source": "/important-information/rc-network-disclaimer",
       "destination": "/learn/network/overview"
     },
-    {
-      "source": "/network#celo-alfajores-l2-testnet",
-      "destination": "/learn/network/overview"
-    },
-    {
-      "source": "/network#celo-baklava-l2-testnet",
-      "destination": "/learn/network/overview"
-    },
     {
       "source": "/network/alfajores/run-full-node",
       "destination": "/operate/operators/run-node"
@@ -3003,22 +2915,6 @@
       "source": "/why-celo",
       "destination": "/learn/index"
     },
-    {
-      "source": "/why-celo#celo-is-mobile-open-and-real",
-      "destination": "/learn/index"
-    },
-    {
-      "source": "/why-celo#mobile",
-      "destination": "/learn/index"
-    },
-    {
-      "source": "/why-celo#open",
-      "destination": "/learn/index"
-    },
-    {
-      "source": "/why-celo#real",
-      "destination": "/learn/index"
-    },
     {
       "source": "/overview",
       "destination": "/learn/index"

scripts/README.md

@@ -5,6 +5,12 @@ This directory contains utility scripts for maintaining and updating the Celo do
 ## Available Scripts
 
 - `update_contracts.py` - Updates contract addresses and deployment information in the documentation
+- `check_redirects.py` - Fails on `docs.json` redirects that cannot work: `#` in a source, a wildcard
+  shadowed by an earlier or identical one, a source that captures a page in navigation, a navigation
+  link to a redirected path, or a destination that is `/`, redirected again, or not a page in
+  navigation. It only understands a trailing `/:slug*` wildcard and stops with an error on any other
+  path parameter. CI runs it with its tests (`python3 -m unittest discover -s scripts -p 'test_*.py'`).
+- `check-orphans.sh` - Fails on page files that navigation does not reach. CI runs it.
 
 ### Generated pages