finish minimal shell standardization efforts (exercism#1184)

* capture other documentation from issue discussion

* space header

* style and more reasons

* simple file name linter

* remove macOSisms

* add to CI

* lint a couple files

* lint a couple files

* fix incorrect path

* convert check exercises tool

* convert check exercises tool

* Apply suggestions from code review

Co-authored-by: Peter Goodspeed-Niklaus <[email protected]>

* count ignores lint

* verify difficulties lint

* allow invalidation search to be empty

Co-authored-by: Peter Goodspeed-Niklaus <[email protected]>

.github/workflows/tests.yml

@@ -21,20 +21,23 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v2
 
+      - name: Ensure tool names are snake cased
+        run: ./bin/lint_tool_file_names.sh
+
       - name: Ensure src/lib.rs files exist
-        run: ./_test/ensure-lib-src-rs-exist.sh
+        run: ./_test/ensure_lib_src_rs_exist.sh
 
       - name: Count ignores
-        run: ./_test/count-ignores.sh
+        run: ./_test/count_ignores.sh
 
       - name: Check UUIDs
-        run: ./_test/check-uuids.sh
+        run: ./_test/check_uuids.sh
 
       - name: Verify exercise difficulties
-        run: ./_test/verify-exercise-difficulties.sh
+        run: ./_test/verify_exercise_difficulties.sh
 
       - name: Check exercises for authors
-        run: ./_test/check-exercises-for-authors.sh
+        run: ./_test/check_exercises_for_authors.sh
 
       - name: Ensure relevant files do not have trailing whitespace
         run: ./bin/lint_trailing_spaces.sh
@@ -117,19 +120,19 @@ jobs:
       - name: Check exercises
         env:
           DENYWARNINGS: ${{ matrix.deny_warnings }}
-        run: ./_test/check-exercises.sh
+        run: ./_test/check_exercises.sh
         continue-on-error: ${{ matrix.rust == 'beta' && matrix.deny_warnings == '1' }}
 
       - name: Ensure stubs compile
         env:
           DENYWARNINGS: ${{ matrix.deny_warnings }}
-        run: ./_test/ensure-stubs-compile.sh
+        run: ./_test/ensure_stubs_compile.sh
         continue-on-error: ${{ matrix.rust == 'beta' && matrix.deny_warnings == '1' }}
 
       - name: Check exercise crate
         env:
           DENYWARNINGS: ${{ matrix.deny_warnings }}
-        run: ./_test/check-exercise-crate.sh
+        run: ./_test/check_exercise_crate.sh
         continue-on-error: ${{ matrix.rust == 'beta' && matrix.deny_warnings == '1' }}
 
   rustformat:
@@ -190,12 +193,12 @@ jobs:
       - name: Clippy tests
         env:
           CLIPPY: true
-        run: ./_test/check-exercises.sh
+        run: ./_test/check_exercises.sh
 
       - name: Clippy stubs
         env:
           CLIPPY: true
-        run: ./_test/ensure-stubs-compile.sh
+        run: ./_test/ensure_stubs_compile.sh
 
   nightly-compilation:
     name: Check exercises on nightly (benchmark enabled)
@@ -222,4 +225,4 @@ jobs:
       - name: Check exercises
         env:
           BENCHMARK: '1'
-        run: ./_test/check-exercises.sh
+        run: ./_test/check_exercises.sh

README.md

@@ -58,7 +58,7 @@ Before submitting your pull request, you'll want to verify the changes in two wa
 * Run all the tests for the Rust exercises
 * Run an Exercism-specific linter to verify the track
 
-All the tests for Rust exercises can be run from the top level of the repo with `_test/check-exercises.sh`. If you are on a Windows machine, there are additional [Windows-specific instructions](_test/WINDOWS_README.md) for running this.
+All the tests for Rust exercises can be run from the top level of the repo with `_test/check_exercises.sh`. If you are on a Windows machine, there are additional [Windows-specific instructions](_test/WINDOWS_README.md) for running this.
 
 ### On modifying the exercises' README
 
@@ -94,7 +94,7 @@ Note that:
                               Cargo.lock              <- Auto generated
                               README.md               <- Instructions for the exercise (see notes below)
 
-- The stub file and test suite should use only the Rust core libraries. `Cargo.toml` should not list any external dependencies as we don't want to make the student assume required crates. If an `example.rs` uses external crates, include `Cargo-example.toml` so that `_tests/check-exercises.sh` can compile with these when testing.
+- The stub file and test suite should use only the Rust core libraries. `Cargo.toml` should not list any external dependencies as we don't want to make the student assume required crates. If an `example.rs` uses external crates, include `Cargo-example.toml` so that `_tests/check_exercises.sh` can compile with these when testing.
 
 - Except in extraordinary circumstances, the stub file should compile under `cargo test --no-run`.
   This allows us to check that the signatures in the stub file match the signatures expected by the tests.

_test/WINDOWS_README.md

@@ -1,6 +1,6 @@
-# check-exercises.sh for Windows Rust Developers
+# check_exercises.sh for Windows Rust Developers
 
-It is possible to run `check-exercises.sh` on Windows 10, pointing to the Windows location for your GitHub repository.  This is done with the Ubuntu on Windows subsystem.
+It is possible to run `check_exercises.sh` on Windows 10, pointing to the Windows location for your GitHub repository.  This is done with the Ubuntu on Windows subsystem.
 
 ## Enable Developer Mode
 To run Ubuntu on Windows, you need to be in Developer Mode.
@@ -39,6 +39,6 @@ You also need to install a cc linker for Rust.
 ## Running Tests
 
     cd /mnt/c/[path of github project]
-    _test/check-exercises.sh
+    _test/check_exercises.sh
 
 This will re-download and build any crates needed, as they only existed in your Windows Rust.

_test/check-exercises.sh → _test/check_exercises.sh

@@ -19,7 +19,7 @@ if [ -z "$DENYWARNINGS" ] && [ -z "$CLIPPY" ]; then
 fi
 
 # can't benchmark with a stable compiler; to bench, use
-# $ BENCHMARK=1 rustup run nightly _test/check-exercises.sh
+# $ BENCHMARK=1 rustup run nightly _test/check_exercises.sh
 if [ -n "$BENCHMARK" ]; then
     target_dir=benches
 else

bin/lint_tool_file_names.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+# Require that internal shell script file names use snake_case
+set -eo pipefail
+
+# find a list of files whose names do not match our convention
+errant_files=$(find bin/ _test/ -iname '*\.sh' -exec basename {} \; | grep '[^a-z_.]' || test 1)
+
+if [ -n "$errant_files" ]; then
+    echo "These file names do not follow our snake case convention:"
+    # find them again to print the whole relative path
+    while IFS= read -r file_name; do
+        find . -name "$file_name"
+    done <<< "$errant_files"
+    echo "Please correct them!"
+    exit 1
+fi

docs/maintaining.md

@@ -16,20 +16,24 @@ This is non-exhaustive.
   - prefer using tools that are ubiquitous: `jq` or `sed` instead of `prettier` or `sd`
   - write scripts to do one thing well
   - prefer GNU versions of `sed` and other utilities
-- Prefer BASH for scripting
+- Prefer Bash for scripting
+  - Strive for compatibility. macOS still distributes Bash v3.x by default, despite v5.x being current; this means that the scripts can't depend on certain features like map.
 - Scripts should use `#!/usr/bin/env bash` as their shebang
   - This increases portability on NixOS and macOS because contributors' preferred bash may not be installed in `/bin/bash`.
-- Prefer snakecase for script file names
+- Prefer snake case for script file names
     ```sh
     hello_world.sh
     ```
+   - This simplifies development when upgrading a script into a proper language. *Rusty tooling anyone?*
 - Script file names should include the `.sh` extension
+- Set the executable bit on scripts that should be called directly.
 - Scripts should set the following options at the top
     ```bash
     set -eo pipefail
     ```
 
 ## Running CI Locally
+
 You can run CI tools locally.
 Scripts expect GNU versions of tooling, so you may see unexpected results on macOS.
 [Here](https://github.com/exercism/rust/issues/1138) is one example.

exercises/practice/paasio/.meta/ignore-count-ignores

@@ -1,2 +1,2 @@
 paasio has tests generated by macro.
-This breaks the count-ignores.sh script.
+This breaks the count_ignores.sh script.

exercises/practice/perfect-numbers/.meta/ignore-count-ignores

@@ -1,5 +1,5 @@
 Perfect numbers has tests generated by macro.
-This breaks the count-ignores.sh script:
+This breaks the count_ignores.sh script:
 
 ```text
 exercises/perfect-numbers/tests/perfect-numbers.rs: Has 2 tests and 11 ignores (should be 1)

exercises/practice/xorcism/.meta/ignore-count-ignores

@@ -1,2 +1,2 @@
 xorcism has tests generated by macro.
-This breaks the count-ignores.sh script.
+This breaks the count_ignores.sh script.