ci: auto-sort and validate systems.csv on PRs

[fredericsimard]

What

Adds automated checks that run on every pull request that changes systems.csv, plus a data sort so the catalog starts in a sorted state.

New workflow: .github/workflows/systems_csv_pr_checks.yml

Job	Behavior
sort	Re-sorts systems.csv and pushes the result back to the PR branch as a separate chore: sort systems.csv commit. Same-repo branches only — fork PRs are skipped (the default GITHUB_TOKEN cannot push to forks).
validate-structure	Fails on malformed rows (wrong field count / broken quoting) and empty required columns (Country Code, Name, Location, System ID, URL, Auto-Discovery URL). Empty Supported Versions → warning; the 3 Authentication columns are optional. Emits inline PR annotations.
check-new-urls	For URLs newly added by the PR (both URL and Auto-Discovery URL columns), follows redirects and requires a final HTTP 200–299. Pre-existing URLs are ignored.

New scripts (scripts/)

• sort-systems-csv.sh — mirrors the canonical (head -n 1; LC_ALL=en_US.UTF-8 sort -t, -k1,1 -k2,2) < systems.csv. Supports --check and a GNUSORT=gsort override for macOS.
• validate-systems-csv.js — structure validator (Node, no deps).
• check-new-urls.js — new-URL HTTP checker (Node, no deps; retries once on transient network errors).

Other changes

• chore: sort systems.csv — applies the sort now (3 rows reordered).
• README.md — the "keep this list alphabetized" note now explains the automated sort in plain and technical terms, with local-repro instructions.

Notes / decisions

• Fork PRs: auto-sort commit is skipped (can't push to forks); structure and URL checks still run.
• URL check covers both URL columns per request; operator homepages occasionally return 403/429 to CI bots, which would fail a PR — worth watching in practice.

Test evidence (local)

• Sort: idempotent; --check correctly flags unsorted input.
• Structure: current file passes with 1 warning (empty Supported Versions); synthetic malformed rows correctly flagged.
• URL check: pre-existing URLs ignored, new URLs from both columns checked, passes on 2xx / fails on non-2xx.

🤖 Generated with Claude Code

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ fredericsimard
❌ github-actions[bot]
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[Copilot]

Addressed by subsequent commits

Pull request overview

Adds automated pull-request checks around systems.csv to keep the catalog consistently sorted and to validate new/changed entries, with supporting scripts and contributor documentation updates.

Changes:

• Introduces a new PR workflow to auto-sort systems.csv, validate CSV structure/required fields, and HTTP-check newly added URLs.
• Adds three new helper scripts under scripts/ to implement sorting, structural validation, and new-URL checking.
• Applies an initial sort to systems.csv and updates README contributor guidance with local reproduction instructions.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
systems.csv	Reorders a handful of rows to match the new canonical sort order.
scripts/validate-systems-csv.js	Adds a Node-based structure/required-field validator emitting GitHub Actions annotations.
scripts/sort-systems-csv.sh	Adds an in-repo canonical sort implementation (header preserved; GNU sort keys).
scripts/check-new-urls.js	Adds a Node-based checker that verifies newly introduced URLs return final 2xx after redirects.
README.md	Updates contributor instructions to describe the automated sort and local reproduction steps.
.github/workflows/systems_csv_pr_checks.yml	New workflow wiring sorting + validation + URL checks on PRs touching systems.csv.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

scripts/check-new-urls.js:163

• The SSRF guard can be bypassed via DNS rebinding: hostIsSafe() resolves the hostname and checks the returned IPs, but http(s).request() will do its own DNS lookup at connection time (which may return a different/private address). Add a lookup option to the request that validates the resolved address with isBlockedIp() before connecting, so the safety check is enforced at the actual socket connection step as well.

      {
        method: 'GET',
        headers: { 'User-Agent': USER_AGENT, Accept: '*/*' },
        timeout: TIMEOUT_MS,
      },

[richfab]

Thank you @fredericsimard.

Is it possible to do the sorting on the first four columns (as mentioned here) please?

Indeed, some operators like "Check Technologies" and "Bolt Technology OÜ" use the same name in all their locations.

[fredericsimard]

@richfab The sort has been updated to use the first 4 columns, the sort was applied and produced no changes. README has been updated to reflect the 4-column key sorting.

[davidgamez]

LGTM

[fredericsimard]

Cross-platform verification of the sort on Ubuntu/Linux

Since the auto-sort job commits back to the PR branch, the sort has to be bit-for-bit reproducible across platforms — if a contributor's local sort disagrees with the runner's, the two fight in a loop and the bot pushes a re-sort on every push. This PR already hit that failure mode once: the original implementation used LC_ALL=en_US.UTF-8, and the Linux runner reordered 25 rows relative to a local macOS sort, producing an unwanted chore: sort systems.csv commit (88ef2a1). The fix was to switch to byte-wise ordering and to implement the comparison in-script rather than delegating collation to the platform.

This comment records the verification that the fix actually holds on Linux.

Test environment

Run under Ubuntu in a container, i.e. the same family as ubuntu-latest on the runner:

Component	Version
Distro	Ubuntu 26.04 LTS
awk	mawk 1.3.4 20260129
sort	uutils coreutils 0.8.0

Two things here are deliberately unlike the macOS dev environment, which is what makes the test meaningful:

• awk is mawk, not the BSD/one-true-awk (awk version 20200816) used on macOS. The shell sorter parses CSV fields in awk, so a behavioral difference here would show up directly in the ordering.
• sort is uutils coreutils (the Rust reimplementation) rather than GNU coreutils. The shell sorter's ordering therefore does not depend on any GNU-specific sort behavior.

What was checked

1. --check against the committed systems.csv — reports already sorted, exit 0.
2. Shuffled round-trip: all 1520 data rows shuffled, then re-sorted on Linux with scripts/sort-systems-csv.sh, and compared to the committed file. This is the real test — a no-op --check on an already-sorted file proves very little on its own.
3. Placement of the two CSV-quoted rows whose Name contains a comma, which were the subject of the CSV-quoting review comment.

Results

=== 1. --check on pristine committed file ===
/tmp/orig.csv is already sorted.
exit=0

=== 2. shuffle all rows, re-sort, compare to committed order ===
Sorted /tmp/shuf.csv.
PASS: Linux sorter reproduces the committed order byte-for-byte

=== 3. quoted-comma rows placed correctly? ===
1516:US,"Veo University of Illinois, Urbana-Champaign","Urbana, IL",veo-iuc,...
1311:SE,"Styr & Ställ (Sweden, Göteborg)",Göteborg,nextbike_zg,...

Both quoted rows land at the same line numbers as on macOS (1516 and 1311), in their correct alphabetical positions rather than pinned to the top of their country block.

Conclusion

Three independent implementations agree byte-for-byte on the full dataset:

Implementation	Platform
scripts/sort-systems-csv.js (Node)	macOS
scripts/sort-systems-csv.sh (bash + BSD awk)	macOS
scripts/sort-systems-csv.sh (bash + mawk + uutils sort)	Ubuntu 26.04

This is consistent with what CI now shows: the Sort systems.csv job logs systems.csv is already sorted; no changes. and pushes no commit, whereas the earlier en_US.UTF-8 version did.

Reproducing

Any Linux environment works. Using Apple's container on macOS:

container run --rm -v "$PWD:/repo" -w /tmp ubuntu:latest bash -lc '
  cp /repo/systems.csv /tmp/o.csv
  cp /repo/scripts/sort-systems-csv.sh /tmp/
  { head -n1 /tmp/o.csv; tail -n +2 /tmp/o.csv | shuf; } > /tmp/s.csv
  bash /tmp/sort-systems-csv.sh /tmp/s.csv >/dev/null
  cmp -s /tmp/s.csv /tmp/o.csv && echo PASS || { echo FAIL; diff /tmp/s.csv /tmp/o.csv | head; }'

The script copies to /tmp before sorting, so the mounted working tree is never modified. The equivalent Docker invocation is the same command with docker in place of container.

[richfab]

@fredericsimard Is possible to ignore the case? "nextbike" should appear after "LiBike". Thank you in advance

[richfab]

@fredericsimard I'd like to take some time to rewrite the section about the sorting in the README, which I will do when I return from vacation on August 31, 2026.

Indeed, external contributions will always come from a fork (as far as I know) and I can see in the README that the automated sorting action cannot run for PRs in forks.

Let's put this on pause until I return. Thank you very much for your support on this.

[fredericsimard]

@richfab no problem. I fixed the sorting issue, it's been committed to this PR. See 6a98ab2 (this PR)