From 4e77a2f6a70350a4dbe3c35579f679a87d0173b4 Mon Sep 17 00:00:00 2001
From: undergroundwires <git@undergroundwires.dev>
Date: Sun, 26 Jan 2025 15:57:21 +0100
Subject: [PATCH] Fix markdown URL check false negatives in CI/CD

This commit improves CI/CD workflows reliability by configuring URL
validation to avoid false positives.

The separate config files makes URL validation rules more maintainable
and easier to update. Allowlisting specific domains prevents workflow
disruptions.

Key changes:

- Move URL validation config to dedicated file for better
  maintainability
- Add allowlist for known valid domains triggering false negatives
- Update GitHub docs URL to prevent link failures
---
 .github/workflows/checks.quality.yaml |  2 +-
 .remark-lint-no-dead-urls.js          | 23 +++++++++++++++++++++++
 docs/ci-cd.md                         |  2 +-
 package.json                          |  2 +-
 4 files changed, 26 insertions(+), 3 deletions(-)
 create mode 100644 .remark-lint-no-dead-urls.js

diff --git a/.github/workflows/checks.quality.yaml b/.github/workflows/checks.quality.yaml
index ca75b0793..448db67db 100644
--- a/.github/workflows/checks.quality.yaml
+++ b/.github/workflows/checks.quality.yaml
@@ -15,7 +15,7 @@ jobs:
           - npm run lint:md:relative-urls
           - npm run lint:md:external-urls
         os: [ macos, ubuntu, windows ]
-      fail-fast: false # Still interested to see results from other combinations
+      fail-fast: false # Still interested to see results from other commands
     steps:
       -
         name: Checkout
diff --git a/.remark-lint-no-dead-urls.js b/.remark-lint-no-dead-urls.js
new file mode 100644
index 000000000..6e70cd244
--- /dev/null
+++ b/.remark-lint-no-dead-urls.js
@@ -0,0 +1,23 @@
+import remarkLintNoDeadUrls from 'remark-lint-no-dead-urls';
+
+/** @type {import('remark-lint-no-dead-urls').Options} */
+const Options = {
+  skipUrlPatterns: [
+    // These result in false negatives
+    'archive.ph',
+    'scoop.sh',
+    'localhost',
+    'archive.org',
+  ].map(buildUrlPattern),
+};
+
+/** @type {Omit<import('unified-engine').Preset} */
+export default {
+  plugins: [[remarkLintNoDeadUrls, Options]],
+};
+
+function buildUrlPattern(fqdn) {
+  const escaped = fqdn.replace(/\./g, '\\.');
+    // Matches http(s)://<domain>[:port]/<path>
+  return `^https?://${escaped}(?::\\d+)?/.*$`;
+}
diff --git a/docs/ci-cd.md b/docs/ci-cd.md
index f85d8a375..4806a1fec 100644
--- a/docs/ci-cd.md
+++ b/docs/ci-cd.md
@@ -42,4 +42,4 @@ Convention for naming pipeline files: **`<type>.<name>.yaml`**.
 - Kebab-case allows to have better URL references to them.
   - [README.md](./../README.md) uses URL references to show status badges for actions.
 
-[1]: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#about-yaml-syntax-for-workflows
+[1]: https://web.archive.org/web/20250126141528/https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#about-yaml-syntax-for-workflows "Workflow syntax for GitHub Actions - GitHub Docs | docs.github.com"
diff --git a/package.json b/package.json
index e5eab3707..3b89798b4 100644
--- a/package.json
+++ b/package.json
@@ -28,7 +28,7 @@
     "lint:md": "markdownlint **/*.md --ignore node_modules",
     "lint:md:consistency": "remark . --frail --use remark-preset-lint-consistent",
     "lint:md:relative-urls": "remark . --frail --use remark-validate-links",
-    "lint:md:external-urls": "remark . --frail --use remark-lint-no-dead-urls",
+    "lint:md:external-urls": "remark . --frail --rc-path .remark-lint-no-dead-urls.js",
     "lint:yaml": "yamllint **/*.yaml --ignore=node_modules/**/*.yaml",
     "lint:pylint": "pylint **/*.py",
     "postinstall": "electron-builder install-app-deps",