testers.shellcheck: init

Needed for testing upcoming commit.

(cherry picked from commit 3fb14db08a)

doc/build-helpers/testers.chapter.md

@@ -116,6 +116,55 @@ It has two modes:
 
 : The `lychee` package to use.
 
+## `shellcheck` {#tester-shellcheck}
+
+Runs files through `shellcheck`, a static analysis tool for shell scripts.
+
+:::{.example #ex-shellcheck}
+# Run `testers.shellcheck`
+
+A single script
+
+```nix
+testers.shellcheck {
+  name = "shellcheck";
+  src = ./script.sh;
+}
+```
+
+Multiple files
+
+```nix
+let
+  inherit (lib) fileset;
+in
+testers.shellcheck {
+  name = "shellcheck";
+  src = fileset.toSource {
+    root = ./.;
+    fileset = fileset.unions [
+      ./lib.sh
+      ./nixbsd-activate
+    ];
+  };
+}
+```
+
+:::
+
+### Inputs {#tester-shellcheck-inputs}
+
+[`src` (path or string)]{#tester-shellcheck-param-src}
+
+: The path to the shell script(s) to check.
+  This can be a single file or a directory containing shell files.
+  All files in `src` will be checked, so you may want to provide `fileset`-based source instead of a whole directory.
+
+### Return value {#tester-shellcheck-return}
+
+A derivation that runs `shellcheck` on the given script(s).
+The build will fail if `shellcheck` finds any issues.
+
 ## `testVersion` {#tester-testVersion}
 
 Checks that the output from running a command contains the specified version string in it as a whole word.

pkgs/build-support/testers/default.nix

@@ -151,4 +151,6 @@
   hasPkgConfigModules = callPackage ./hasPkgConfigModules/tester.nix { };
 
   testMetaPkgConfig = callPackage ./testMetaPkgConfig/tester.nix { };
+
+  shellcheck = callPackage ./shellcheck/tester.nix { };
 }

pkgs/build-support/testers/shellcheck/example.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+echo $@

pkgs/build-support/testers/shellcheck/tester.nix

@@ -0,0 +1,28 @@
+# Dependencies (callPackage)
+{ lib, stdenv, shellcheck }:
+
+# testers.shellcheck function
+# Docs: doc/build-helpers/testers.chapter.md
+# Tests: ./tests.nix
+{ src }:
+let
+  inherit (lib) fileset pathType isPath;
+in
+stdenv.mkDerivation {
+  name = "run-shellcheck";
+  src =
+    if isPath src && pathType src == "regular" # note that for strings this would have been IFD, which we prefer to avoid
+    then fileset.toSource { root = dirOf src; fileset = src; }
+    else src;
+  nativeBuildInputs = [ shellcheck ];
+  doCheck = true;
+  dontConfigure = true;
+  dontBuild = true;
+  checkPhase = ''
+    find . -type f -print0 \
+      | xargs -0 shellcheck
+  '';
+  installPhase = ''
+    touch $out
+  '';
+}

pkgs/build-support/testers/shellcheck/tests.nix

@@ -0,0 +1,38 @@
+# Run:
+#   nix-build -A tests.testers.shellcheck
+
+{ lib, testers, runCommand }:
+let
+  inherit (lib) fileset;
+in
+lib.recurseIntoAttrs {
+
+  example-dir = runCommand "test-testers-shellcheck-example-dir" {
+    failure = testers.testBuildFailure
+      (testers.shellcheck {
+        src = fileset.toSource {
+          root = ./.;
+          fileset = fileset.unions [
+            ./example.sh
+          ];
+        };
+      });
+  } ''
+    log="$failure/testBuildFailure.log"
+    echo "Checking $log"
+    grep SC2068 "$log"
+    touch $out
+  '';
+
+  example-file = runCommand "test-testers-shellcheck-example-file" {
+    failure = testers.testBuildFailure
+      (testers.shellcheck {
+        src = ./example.sh;
+      });
+  } ''
+    log="$failure/testBuildFailure.log"
+    echo "Checking $log"
+    grep SC2068 "$log"
+    touch $out
+  '';
+}

pkgs/build-support/testers/test/default.nix

@@ -16,6 +16,8 @@ lib.recurseIntoAttrs {
 
   hasPkgConfigModules = pkgs.callPackage ../hasPkgConfigModules/tests.nix { };
 
+  shellcheck = pkgs.callPackage ../shellcheck/tests.nix { };
+
   runNixOSTest-example = pkgs-with-overlay.testers.runNixOSTest ({ lib, ... }: {
     name = "runNixOSTest-test";
     nodes.machine = { pkgs, ... }: {