From 3b40a26087c35ee8f3fcd070fbf9fcb7ff667049 Mon Sep 17 00:00:00 2001
From: Oleksii Filonenko <12615679+Br1ght0ne@users.noreply.github.com>
Date: Tue, 2 Jul 2024 15:18:55 +0300
Subject: [PATCH] ci(link-checker): use lychee instead of MLC (#34)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR changes
[`mdbook-docs.yml`](../blob/master/.github/workflows/mdbook-docs.yml#L35)
workflow to use https://github.com/lycheeverse/lychee ("Fast, async,
stream-based link checker written in Rust") via
https://github.com/lycheeverse/lychee-action instead of MLC
(`markdown-link-check`).

The lychee config file
([`lychee.toml`](../blob/lychee-link-checker/docs-hub/lychee.toml))
closely mirrors the settings from existing
[`mlc.mdbook.json`](../blob/master/docs-hub/mlc.mdbook.json), and thus
should work with any and all Markdown files. I opted to leave
`mlc.next.json` as-is for now, because it uses extra configuration.

Reasoning for the change:
- main reason - `markdown-link-check` operates on individual files
(e.g., `find . -name *md -exec markdown-link-check {};`). This means
that the errors are reported in the middle of the job output, which is
quite long. Thus, it is difficult to find the actual error message.
`lychee` uses globs like `**/*.md` natively (handled by `lychee-action`
under the hood), meaning that there's a single report for all links in
the repo's Markdown, with errors clearly visible. It looks like this by
default (1 link failing on purpose):
```
  179/179 ━━━━━━━━━━━━━━━━━━━━ Finished extracting links                                                                                                                                                                                             Issues found in 1 input. Find details below.

[docs/src/connecting/external-node.md]:
✗ [403] https://faucet-beta-5.fuel.network/ | Failed: Network error: Forbidden

🔍 179 Total (in 1s) ✅ 177 OK 🚫 1 Error 💤 1 Excluded
```
- `lychee` can use GHA cache to avoid checking the same links on
repeated CI runs - this is configured in this PR
- it's much faster than MLC, written in Rust and well-maintained (+ for
security)
---
 .github/workflows/mdbook-docs.yml | 10 ++++++++--
 docs-hub/lychee.toml              | 20 ++++++++++++++++++++
 2 files changed, 28 insertions(+), 2 deletions(-)
 create mode 100644 docs-hub/lychee.toml

diff --git a/.github/workflows/mdbook-docs.yml b/.github/workflows/mdbook-docs.yml
index 21b3c51..3641151 100644
--- a/.github/workflows/mdbook-docs.yml
+++ b/.github/workflows/mdbook-docs.yml
@@ -32,9 +32,15 @@ jobs:
       - name: Run pre-command
         if: inputs.pre-command != ''
         run: ${{ inputs.pre-command }}
-      - uses: gaurav-nelson/github-action-markdown-link-check@1.0.12
+      - name: Restore lychee cache
+        uses: actions/cache@v3
         with:
-          config-file: 'workflow/docs-hub/mlc.mdbook.json'
+          path: .lycheecache
+          key: cache-lychee-${{ github.ref_name }}
+          restore-keys: cache-lychee-
+      - uses: lycheeverse/lychee-action@v1
+        with:
+          args: '--config workflow/docs-hub/lychee.toml'
 
   markdown-lint:
     name: Markdown Lint
diff --git a/docs-hub/lychee.toml b/docs-hub/lychee.toml
new file mode 100644
index 0000000..a8dcceb
--- /dev/null
+++ b/docs-hub/lychee.toml
@@ -0,0 +1,20 @@
+# Enable link caching. This can be helpful to avoid checking the same links on
+# multiple runs.
+cache = true
+
+# Discard all cached requests older than this duration.
+max_cache_age = "1d"
+
+# Comma-separated list of accepted status codes for valid links.
+accept = ["200", "206", "405"]
+
+# Exclude URLs and mail addresses from checking (supports regex).
+exclude = [
+    'faucet-beta-5.fuel.network',
+    'fuellabs.github.io/block-explorer-v2',
+]
+
+# Exclude all private IPs from checking.
+# Equivalent to setting `exclude_private`, `exclude_link_local`, and
+# `exclude_loopback` to true.
+exclude_all_private = true