Experiment

.gitattributes

@@ -0,0 +1,10 @@
+# Generated maps are written by tools/mapgen/build.py with LF endings. Pin them to LF so a
+# checkout doesn't rewrite them to CRLF on Windows: otherwise `build.py --deploy` reports
+# three modified files whose only change is line endings. Keeps the working tree
+# byte-identical to what the generator produces.
+*.drawio.svg text eol=lf
+*.drawio     text eol=lf
+
+# The map source is likewise generator-written / hand-edited in lockstep with it.
+tools/mapgen/roadmap/*.dsl text eol=lf
+tools/mapgen/roadmap/*.tsv text eol=lf

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,4 +4,5 @@ Please include a summary of the change and which issue is fixed.
 ## Checklist
 - [ ] Content changes have been applied to all three languages (English, Russian, Chinese) OR a follow-up issue has been opened to track missing translations.
 - [ ] Any new external links have been verified. (If a link is bot-blocked and fails CI, it has been added to `.lycheeignore` with a comment).
-- [ ] I have run `lychee` locally to verify links according to `CONTRIBUTING.md`.
+- [ ] I have run `lychee --offline --no-progress "**/*.md"` locally (see `CONTRIBUTING.md`); if I added external links, I checked those too.
+- [ ] **If I changed the map**: I edited `tools/mapgen/roadmap/` (not the `.drawio.svg`), rebuilt with `python tools/mapgen/build.py --dir tools/mapgen/roadmap --deploy --check`, and committed the regenerated maps — or I said in the description that a maintainer needs to regenerate them.

.github/workflows/check-links.yml

@@ -1,51 +1,40 @@
+# Fast, deterministic link check that runs on every PR.
+#
+# This checks ONLY internal links -- relative paths between files in the repo. Those are
+# the ones a PR can actually break (a moved file, a wrong ../ prefix), and they never fail
+# for reasons outside the repo, so this check is safe to require for merge. It takes
+# milliseconds because nothing goes over the network.
+#
+# External URLs are NOT checked here on purpose. There are ~370 of them; any one being
+# down, rate-limited, or blocking datacenter IPs would fail an unrelated PR. They are swept
+# monthly instead by link-audit.yml, which opens an issue rather than blocking anyone.
+
 name: Check links
 
 on:
   pull_request:
-  schedule:
-    # Every Monday at 06:00 UTC
-    - cron: "0 6 * * 1"
+  push:
+    branches: [main]
   workflow_dispatch:
 
 permissions:
   contents: read
 
 jobs:
+  # NOTE: job id `lychee` is deliberate -- the required status check is named
+  # "Check links / lychee". Renaming this job would break branch protection.
   lychee:
+    name: lychee
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      issues: write
     steps:
       - name: Checkout
         uses: actions/checkout@v7
 
-      - name: Restore lychee cache
-        uses: actions/cache@v6
-        with:
-          path: .lycheecache
-          key: cache-lychee-${{ github.sha }}
-          restore-keys: cache-lychee-
-
-      - name: Check links in markdown files
+      - name: Check internal links
         uses: lycheeverse/lychee-action@v2
-        id: lychee
         with:
           args: >-
+            --offline
             --no-progress
-            --accept 200..=204,429
-            --max-retries 2
-            --timeout 45
-            --cache
-            --max-cache-age 1d
             "**/*.md"
           fail: true
-          output: ./lychee/out.md
-
-      - name: Create Issue From File
-        if: failure() && github.event_name == 'schedule'
-        uses: peter-evans/create-issue-from-file@v6
-        with:
-          title: Link Checker Report
-          content-filepath: ./lychee/out.md
-          labels: report, automated issue

.github/workflows/link-audit.yml

@@ -0,0 +1,75 @@
+# Monthly sweep of every EXTERNAL link in the repo.
+#
+# Split out of check-links.yml so that third-party outages never block a pull request.
+# This workflow does not gate anything: it runs on the 1st of each month, and when it
+# finds dead links it files (or updates) a single "Link Checker Report" issue to work
+# through when convenient. Run it on demand any time from the Actions tab.
+#
+# Fixing what it reports: replace the dead link, or -- if the site is alive in a browser
+# but blocks CI (403/415/redirect loop from datacenter IPs) -- add it to .lycheeignore
+# with a comment saying why. See CONTRIBUTING.md.
+
+name: Link audit
+
+on:
+  schedule:
+    - cron: "0 6 1 * *"     # 06:00 UTC on the 1st of every month
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Restore lychee cache
+        uses: actions/cache@v6
+        with:
+          path: .lycheecache
+          key: cache-lychee-${{ github.sha }}
+          restore-keys: cache-lychee-
+
+      - name: Check all links
+        uses: lycheeverse/lychee-action@v2
+        id: lychee
+        with:
+          args: >-
+            --no-progress
+            --accept 200..=204,429
+            --max-retries 3
+            --retry-wait-time 5
+            --timeout 45
+            --cache
+            --max-cache-age 1d
+            "**/*.md"
+          fail: false                 # never fail the run; the issue is the output
+          output: ./lychee/out.md
+
+      # Reuse one issue instead of opening a new one every month.
+      - name: Find existing report issue
+        if: steps.lychee.outputs.exit_code != 0
+        id: existing
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          num=$(gh issue list --state open --label "automated issue" \
+                  --search "Link Checker Report in:title" \
+                  --json number --jq '.[0].number // empty')
+          echo "number=$num" >> "$GITHUB_OUTPUT"
+          echo "Existing report issue: ${num:-none}"
+
+      - name: File or update the report
+        if: steps.lychee.outputs.exit_code != 0
+        uses: peter-evans/create-issue-from-file@v6
+        with:
+          title: Link Checker Report
+          content-filepath: ./lychee/out.md
+          labels: report, automated issue
+          issue-number: ${{ steps.existing.outputs.number }}

.github/workflows/map-check.yml

@@ -0,0 +1,56 @@
+# Validates the roadmap maps on every PR that touches them or the generator.
+#
+# The three <Language>/Graph/roadmap.drawio.svg maps are build output of tools/mapgen —
+# generated from one language-neutral source (structure.dsl + <lang>.tsv). CI cannot
+# rebuild them (that needs the draw.io desktop CLI), so instead it verifies that what was
+# committed is valid and still matches the source:
+#
+#   1. Unit-test the generator  — DSL parser + hint geometry (no Pillow/draw.io needed).
+#   2. Validate the maps        — tools/mapcheck: text fits its box, nothing overlaps, and
+#                                 the committed maps match structure.dsl / <lang>.tsv
+#                                 (so a forgotten rebuild fails here rather than shipping).
+#
+# Hard errors fail the build; cross-language drift and a stale "Last updated" date are
+# reported as warnings. See tools/mapcheck/README.md.
+
+name: Check maps
+
+on:
+  pull_request:
+    paths:
+      - "*/Graph/roadmap.drawio.svg"
+      - "tools/mapgen/**"          # DSL/tsv source — the map-vs-DSL check compares against it
+      - "tools/mapcheck/**"
+      - ".github/workflows/map-check.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  mapcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0            # date check reads each map's last-commit date
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Unit-test the generator
+        run: python tools/mapgen/test_build.py       # parser + geometry math; no Pillow/draw.io needed
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --quiet Pillow
+          sudo apt-get update -qq
+          # Liberation Sans is metric-compatible with Arial (what draw.io uses);
+          # Noto CJK covers the Chinese map.
+          sudo apt-get install -y -qq fonts-liberation fonts-noto-cjk
+
+      - name: Validate maps
+        run: python tools/mapcheck/check.py

.lycheeignore

@@ -45,3 +45,6 @@ https://www\.sfml-dev\.org.*
 # reports an untrusted certificate. Server-side misconfiguration on their end,
 # nothing we can fix; drop this line once they fix their chain.
 https://www\.autosar\.org.*
+# stackoverflow.com redirects the bare root to /questions and then answers 403 to
+# non-browser clients -- the same bot-detection false positive as reddit/amazon above.
+https://stackoverflow\.com/?$