ci: add scripts-only shellcheck gate

Lint only the scripts directory in CI with configurable ShellCheck excludes, and document the local command contributors should run before pushing.

Made-with: Cursor

Author: yinkscss

.github/workflows/ci.yml

@@ -13,6 +13,7 @@ concurrency:
 env:
   CARGO_TERM_COLOR: always
   RUST_BACKTRACE: 1
+  SHELLCHECK_EXCLUDES: ""
   REGISTRY: ghcr.io
   IMAGE_NAME: ${{ github.repository }}
 
@@ -238,12 +239,17 @@ jobs:
 
       - name: Run shellcheck
         run: |
-          mapfile -t shell_files < <(find . -type f -name "*.sh")
+          mapfile -t shell_files < <(find scripts -type f -name "*.sh")
           if [ "${#shell_files[@]}" -eq 0 ]; then
-            echo "No shell scripts found"
+            echo "No shell scripts found in scripts/"
             exit 0
           fi
-          shellcheck -S error "${shell_files[@]}"
+          shellcheck_cmd=(shellcheck -S error)
+          if [ -n "${SHELLCHECK_EXCLUDES}" ]; then
+            shellcheck_cmd+=(-e "${SHELLCHECK_EXCLUDES}")
+            echo "Running shellcheck with excludes: ${SHELLCHECK_EXCLUDES}"
+          fi
+          "${shellcheck_cmd[@]}" "${shell_files[@]}"
 
       - name: Check formatting
         run: make fmt-check

CONTRIBUTING.md

@@ -117,6 +117,7 @@ Please do not delete the template sections. PRs with empty descriptions or unche
 
 - **Formatting**: Always run `cargo fmt` before committing.
 - **Linting**: We use Clippy. Ensure `cargo clippy --all-targets --all-features -- -D warnings` passes.
+- **Shell scripts**: We lint scripts under `scripts/` with ShellCheck. Run `find scripts -type f -name "*.sh" -print0 | xargs -0 shellcheck -S error` locally.
 - **Security**: All dependencies must be audited. We resolve all `RUSTSEC` advisories immediately.
 - **Error Handling**: Prefer the `Result<T>` type defined in `src/error.rs` using `thiserror`.