Merge pull request #3664 from JacquesCarette/shellcheckScripts

Shellcheck scripts in Lint workflow

.github/workflows/Lint.yaml

@@ -2,7 +2,7 @@ on:
   pull_request:
     branches: main
   workflow_dispatch:
-    paths: [code/drasil-**, .github/workflows/Lint.yaml]
+    paths: [code/drasil-**, .github/workflows/Lint.yaml, code/scripts/**]
 name: Linter
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -13,25 +13,47 @@ defaults:
     working-directory: code
 jobs:
   linter:
-    name: "HLint"
+    name: "Linter"
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
+      # Prepare more specific paths filters
+      - uses: dorny/[email protected]
+        id: filter
+        with:
+           filters: |
+            hs:
+              - '**/*.hs'
+              - '**/*.lhs'
+            sh:
+              - '**/*.sh'
+
+      # If a [l]hs file was edited, then run HLint
       # Once we update our LTS, we can remove this step, see "Inputs": https://github.com/haskell-actions/hlint-setup
       - name: 'Install HLint system dependencies'
+        if: ${{ steps.filter.outputs.hs == 'true' }}
         run: |
           sudo apt-get update
           sudo apt-get install -y libtinfo5
 
       - name: 'Set up HLint'
+        if: ${{ steps.filter.outputs.hs == 'true' }}
         uses: haskell-actions/hlint-setup@v2
         with: # DO NOT MODIFY THE BELOW LINE MANUALLY -- code/scripts/update_default_stackage.sh is in charge of this!
           version: '3.4.1' # HLINT VERSION TIED TO CURRENT TARGET (LTS-20.26)
 
       - name: 'Run HLint'
+        if: ${{ steps.filter.outputs.hs == 'true' }}
         uses: haskell-actions/hlint-run@v2
         with: # The custom hlint-bin is necessary because we need to inject options to hlint, since hlint-run does not support it yet, see: https://github.com/haskell-actions/hlint-run/issues/20
           hlint-bin: hlint --hint=code/.hlint.yaml
           path: code/
           fail-on: status
+
+      # If a sh script was edited, then run shellcheck
+      - name: "Run ShellCheck"
+        if: ${{ steps.filter.outputs.sh == 'true' }}
+        uses: ludeeus/[email protected]
+        with:
+          scandir: './code/scripts'

code/Makefile

@@ -407,16 +407,19 @@ convertAnalyzed: ##@Analysis Convert analyzed dot graphs into SVGs.
 	@echo "Dependency graphs built, check your '$(TYPEGRAPH_FOLDER)' and '$(CLASSINST_GRAPH_FOLDER)' folders."
 
 #---------------------------------------#
-#--- HLint and Haddock Documentation ---#
+#-- Linters and Haddock Documentation --#
 #---------------------------------------#
 
-hlint: check_stack ##@HLint Run HLint through the drasil packages. Uses a local HLint installation.
+hlint: check_stack ##@Linters Run HLint through the drasil packages. Uses a local HLint installation.
 	stack install hlint
 	hlint .
 
-hot_hlint: ##@HLint Run HLint through the drasil packages. Uses the latest HLint version, downloading the binary each time.
+hot_hlint: ##@Linters Run HLint through the drasil packages. Uses the latest HLint version, downloading the binary each time.
 	curl --max-time 60 -sSL https://raw.github.com/ndmitchell/hlint/master/misc/run.sh | sh -s .
 
+shellcheck: ##@Linters Run ShellCheck static analyzer on all shell script files.
+	find . -type f -name '*.sh' -exec shellcheck {} +
+
 docs: check_stack ##@Documentation Create Haddock documentation of all Drasil modules. Set FULL=1 if you want to additionally test Haddock generation for website deployment.
 	FULL="$(FULL)" DOCS_FOLDER="$(DOCS_FOLDER)" GHC_FLAGS="$(GHCFLAGS)" sh scripts/make_docs.sh
 
@@ -555,4 +558,4 @@ help_packages: ##@Help Lists all packages.
 		echo "  $$package"; \
 	done
 
-.PHONY: help clean clean_artifacts cleanArtifacts gool code deps hlint hot_hlint analysis tex doc debug test graphs graphmod check_stack nographs graphs website deploy_code_path deploy deploy_lite all install $(GOOLTEST) $(ALL_EXPANDED_TARGETS)
+.PHONY: help clean clean_artifacts cleanArtifacts gool code deps hlint hot_hlint analysis tex doc debug test graphs graphmod check_stack nographs graphs website deploy_code_path deploy deploy_lite all install examples tracegraphs doxygen $(GOOLTEST) $(ALL_EXPANDED_TARGETS)

code/scripts/check_stack.sh

@@ -3,7 +3,7 @@
 # Ensure Stack version is at least our designated minimum, caching the stack
 # version so we don't need to do this too often.
 
-if [ -z $MIN_STACK_VER ]; then
+if [ -z "$MIN_STACK_VER" ]; then
   echo "Missing MIN_STACK_VER"
   exit 1
 fi
@@ -16,7 +16,7 @@ fi
 if [ -f "$CACHED_MSV_FILE" ]; then
   # Fast exit
   CACHED=$(cat "$CACHED_MSV_FILE")
-  if [ $CACHED = $MIN_STACK_VER ]; then
+  if [ "$CACHED" = "$MIN_STACK_VER" ]; then
     exit 0
   fi
 fi
@@ -29,30 +29,30 @@ fi
 
 CURRENT_VER=$(stack --numeric-version)
 
-MSV_SPACE=$(echo $MIN_STACK_VER | tr "." " ")
-MSV_LEN=$(echo $MSV_SPACE | wc -w)
-CV_SPACE=$(echo $CURRENT_VER | tr "." " ")
-CV_LEN=$(echo $CV_SPACE | wc -w)
+MSV_SPACE=$(echo "$MIN_STACK_VER" | tr "." " ")
+MSV_LEN=$(echo "$MSV_SPACE" | wc -w)
+CV_SPACE=$(echo "$CURRENT_VER" | tr "." " ")
+CV_LEN=$(echo "$CV_SPACE" | wc -w)
 
 VALID_VERSION=yes
-for i in $(seq 1 $MSV_LEN); do
-  if [ $i -gt $CV_LEN ]; then
+for i in $(seq 1 "$MSV_LEN"); do
+  if [ "$i" -gt "$CV_LEN" ]; then
     VALID_VERSION=no
     break
   fi
 
-  CVV=$(echo $CV_SPACE | cut -d" " -f$i)
-  MSVV=$(echo $MSV_SPACE | cut -d" " -f$i)
-  if [ $CVV -ne $MSVV ]; then
-    if [ $CVV -lt $MSVV ]; then
+  CVV=$(echo "$CV_SPACE" | cut -d" " -f"$i")
+  MSVV=$(echo "$MSV_SPACE" | cut -d" " -f"$i")
+  if [ "$CVV" -ne "$MSVV" ]; then
+    if [ "$CVV" -lt "$MSVV" ]; then
       VALID_VERSION=no
     fi
     break
   fi
 done
 
 if [ $VALID_VERSION = "yes" ]; then
-  echo $MIN_STACK_VER > "$CACHED_MSV_FILE"
+  echo "$MIN_STACK_VER" > "$CACHED_MSV_FILE"
   exit 0
 else
   echo "It appears your version of stack is out of date."

code/scripts/code_build.sh

@@ -15,29 +15,30 @@ fi
 
 build_code () {
   if [ -d "$EXAMPLE_CODE_SUBFOLDER" ]; then
-    cd "$EXAMPLE_CODE_SUBFOLDER"
+    cd "$EXAMPLE_CODE_SUBFOLDER" || exit 1
     OLD_DIR=$(pwd)
     for dr in */; do
-      cd "$dr"
+      cd "$dr" || exit 1
       if [ -d "$ROOT_DIR/$DF_DIR$EDIR/$dr" ]; then
         cp -r "$ROOT_DIR/$DF_DIR$EDIR/$dr"* "."
       fi
+      # shellcheck disable=SC2086
       "$MAKE" $TARGET
-      RET=$(( $RET || $? ))
-      cd "$OLD_DIR"
+      RET=$(( "$RET" || $? ))
+      cd "$OLD_DIR" || exit 1
     done
   fi
 }
 
 RET=0
 ROOT_DIR=$(pwd)
-cd "$BUILD_FOLDER$EDIR"
+cd "$BUILD_FOLDER$EDIR" || exit 1
 if [[ "$MULTI_SRC_DIRS" == *"$EDIR"* ]]; then
   E_DIR=$(pwd)
   for d in */; do
-    cd "$d"
+    cd "$d" || exit 1
     build_code
-    cd "$E_DIR"
+    cd "$E_DIR" || exit 1
   done
 fi
 

code/scripts/duplicate_string_get_information.sh

@@ -2,7 +2,7 @@
 
 # -r so that Backslash does not act as an escape character, so that escape characters are captured
 while read -r  p; do
-    echo $p >>duplicate_string_summary.txt
+    echo "$p" >>duplicate_string_summary.txt
     #looking for instances of \\, grep needs to be adjusted for escape characters
     if [[ $p == *"\\"* ]]; then
         #remove the first character (double quote) of the current string
@@ -24,7 +24,7 @@ while read -r  p; do
         echo "Number of files containing the string: ${filescontainstring}" >>duplicate_string_summary.txt
         grep -ro --exclude-dir=./Drasil/code/stable --include \*.hs "$p" ./Drasil/code | sort -u >>duplicate_string_summary.txt
     fi    
-    printf '%s\n'>>duplicate_string_summary.txt
+    printf '\n'>>duplicate_string_summary.txt
 done <duplicate_strings.txt
 
 

code/scripts/gooltest_build.sh

@@ -1,3 +1,5 @@
+#!/usr/bin/env bash
+
 if [ -z "$EDIR" ]; then
   echo "Missing EDIR."
   exit 1
@@ -9,18 +11,19 @@ fi
 
 RET=0
 
-cd "$BUILD_FOLDER$EDIR"
+cd "$BUILD_FOLDER$EDIR" || exit 1
 E_DIR=$(pwd)
 for lang in */; do
-  cd "$lang"
+  cd "$lang" || exit 1
   LANG_DIR=$(pwd)
   for test in */; do
-    cd "$test"
+    cd "$test" || exit 1
+    # shellcheck disable=SC2086
     "$MAKE" $TARGET
-    RET=$(( $RET || $? ))
-    cd "$LANG_DIR"
+    RET=$(( "$RET" || $? ))
+    cd "$LANG_DIR" || exit 1
   done
-  cd "$E_DIR"
+  cd "$E_DIR" || exit 1
 done
 
 exit $RET

code/scripts/make_docs.sh

@@ -21,9 +21,7 @@ mkdir -p "$FULL_DOCS_FOLDER"
 # Get location of buildable docs location
 
 # Build full variant
-stack haddock --haddock-arguments "--show-all" --ghc-options="$GHC_FLAGS"
-
-if [ "$?" -eq "0" ]; then
+if stack haddock --haddock-arguments "--show-all" --ghc-options="$GHC_FLAGS"; then
   echo "Successfully created fully exposed variant of Haddock docs!"
 else
   echo "Fully exposed Haddock build failed!"
@@ -46,9 +44,7 @@ cp -rf "$DOCS_LOC/." "$FULL_DOCS_FOLDER"
 stack clean
 
 # Build small variant
-stack haddock --ghc-options="$GHC_FLAGS"
-
-if [ "$?" -eq "0" ]; then
+if stack haddock --ghc-options="$GHC_FLAGS"; then
   echo "Successfully created normal Haddock docs!"
 else
   echo "Normal Haddock build failed!"

code/scripts/prepare_deployment.sh

@@ -134,7 +134,7 @@ src_stub() {
   REL_PATH=$(cd "$CUR_DIR" && "$MAKE" deploy_code_path | grep "$example_name" | cut -d"$DEPLOY_CODE_PATH_KV_SEP" -f 2-)
   # On a real deploy, `deploy` folder is itself a git repo, thus we need to ensure the path lookup is in the outer Drasil repo.
   for p in $REL_PATH; do
-    ls -d "$(cd "$CUR_DIR" && git rev-parse --show-toplevel)/$p"*/ | rev | cut -d/ -f2 | rev | tr '\n' '\0' | xargs -0 printf "$p%s\n" >> "$EXAMPLE_DEST$example_name/src"
+    find "$(cd "$CUR_DIR" && git rev-parse --show-toplevel)" -name "$p*" -type d -print0 | rev | cut -d/ -f2 | rev | tr '\0' '\n' | xargs -0 printf "$p%s\n" >> "$EXAMPLE_DEST$example_name/src"
   done
 }
 
@@ -155,15 +155,15 @@ copy_traceygraphs() {
 }
 
 copy_website() {
-  cd "$CUR_DIR$DEPLOY_FOLDER"
+  cd "$CUR_DIR$DEPLOY_FOLDER" || exit 1
   cp -r "$CUR_DIR$WEBSITE_FOLDER". .
 
   # src stubs were consumed by site generator; safe to delete those.
   rm "$EXAMPLE_DEST"*/src
 }
 
 
-cd "$DEPLOY_FOLDER"
+cd "$DEPLOY_FOLDER" || exit 1
 copy_docs
 copy_graphs
 copy_datafiles
@@ -172,4 +172,4 @@ copy_images
 copy_analysis
 copy_traceygraphs
 copy_website
-cd "$CUR_DIR"
+cd "$CUR_DIR" || exit 1

code/scripts/tex_build.sh

@@ -24,17 +24,17 @@ fi
 
 GEN_NAME_SUFFIX=_SRS
 
-cd "$BUILD_FOLDER$EDIR"/SRS/PDF
+cd "$BUILD_FOLDER$EDIR"/SRS/PDF || exit 1
 "$MAKE" TEXFLAGS="-interaction=$IMODE --shell-escape" BIBTEXFLAGS="$BIFLAGS"
 RET=$?
 
 if [ "$SUMMARIZE_TEX" = "yes" ]; then
-  echo "\n\n\033[0;33m$EDIR TeX Summary\033[0m:"
+  printf "\n\n\033[0;33m%s TeX Summary\033[0m:" "$EDIR"
   if [ "$RET" -eq 0 ]; then
     # Approximate error gathering from TeX logs.
-    cat "$EDIR$GEN_NAME_SUFFIX".log | grep -E "erfull|Warning"
-    cat "$EDIR$GEN_NAME_SUFFIX".blg | grep -B3 -E "Error"
-    BIBERRS=$(cat "$EDIR$GEN_NAME_SUFFIX".blg | grep -E "Error" | wc -l)
+    grep -E "erfull|Warning" "$EDIR$GEN_NAME_SUFFIX".log
+    grep -B3 -E "Error" "$EDIR$GEN_NAME_SUFFIX".blg
+    BIBERRS=$(grep -c -E "Error" "$EDIR$GEN_NAME_SUFFIX".blg)
     if [ "$BIBERRS" -gt 0 ]; then
       # This conditional is due to the current way TeX makefiles are generated.
       # BibTeX return value is ignored (specifically with HGHC having no

code/scripts/update_default_stackage.sh

@@ -7,15 +7,18 @@ update_files() {
     local search="$3"
     local replace="$4"
 
-    find "$dir" -type f -name "$targets" | while read file; do
+    find "$dir" -type f -name "$targets" | while read -r file; do
         sed -i -E "s|$search|$replace|g" "$file"
         echo "Updated: $file"
     done
 }
 
 fetch_hlint_version() {
-    local redirect_url=$(curl -Ls -o /dev/null -w %{url_effective} "https://www.stackage.org/lts-$1/package/hlint")
-    local hlint_version=$(echo "$redirect_url" | grep -oE "hlint-[0-9]+\.[0-9]+\.[0-9]+" | sed 's/hlint-//')
+    local redirect_url
+    local hlint_version
+
+    redirect_url=$(curl -Ls -o /dev/null -w "%{url_effective}" "https://www.stackage.org/lts-$1/package/hlint")
+    hlint_version=$(echo "$redirect_url" | grep -oE "hlint-[0-9]+\.[0-9]+\.[0-9]+" | sed 's/hlint-//')
 
     echo "$hlint_version"
 }

wiki/New-Workspace-Setup.md

@@ -12,6 +12,7 @@ In order, you should be installing:
 
 Optionally, some functions will be limited without:
 1. [Doxygen](#doxygen)
+2. [ShellCheck](#shellcheck)
 
 **Notes**: 
 1. It is [**recommended**](https://github.com/JacquesCarette/Drasil/issues/2913#issuecomment-987300398) for Windows users to install the following tools using Linux on Windows/Windows WSL. If you choose to install using Windows WSL, you can safely ignore all Windows installation notes (except for that regarding Unicode support), and follow the instructions for Linux machines with the *apt*-package manager (e.g., Debian, Ubuntu, etc). From experience, installations with Windows WSL over native installations provide better tools, quicker installs, and an overall smoother experience.
@@ -496,5 +497,52 @@ The [Doxygen download page](https://www.doxygen.nl/download.html) has a disk ima
 
 </details>
 
+## ShellCheck
+
+ShellCheck is integrated into our GitHub CI pipeline, providing static analysis of shell scripts. ShellCheck is required to execute the `make shellcheck` target in our primary `Makefile` to statically analyze shell scripts locally.
+
+### Installation Instructions
+
+Please visit the [ShellCheck GitHub](https://github.com/koalaman/shellcheck?tab=readme-ov-file#installing) for more detailed instructions. For convenience, we have a summary for some Linux distributions, Windows, and Mac below.
+
+<details>
+
+<summary><h4>Linux</h4></summary>
+
+For Ubuntu and Debian, you can use the following command to install ShellCheck:
+```
+sudo apt install shellcheck
+```
+
+</details>
+
+<details>
+
+<summary><h4>Windows</h4></summary>
+
+You can download pre-compiled binaries for the latest release here: [Windows, x86](https://github.com/koalaman/shellcheck/releases/download/stable/shellcheck-stable.zip).
+
+Alternatively, if you have [`chocolatey`](https://chocolatey.org/install) installed, you can open up a new command line as an administrator and run the following command:
+```
+choco install shellcheck
+```
+
+</details>
+
+<details>
+
+<summary><h4>Mac</h4></summary>
+
+If you use [homebrew](https://brew.sh/), you can install via the following command:
+```
+brew install shellcheck
+```
+Or, you can use [MacPorts](https://www.macports.org/):
+```
+sudo port install shellcheck
+```
+
+</details>
+
 # Working with Drasil
 Congratulations! Now that you've successfully setup your workspace, you should move on to our [Contributer's Guide](https://github.com/JacquesCarette/Drasil/wiki/Contributor's-Guide).