From 2b357c3d6e4fab27838202fadcfcf937ad107de6 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Tue, 16 Jul 2024 20:09:45 +0200
Subject: [PATCH] testers.shellcheck: init

Needed for testing upcoming commit.

(cherry picked from commit 3fb14db08a2f7b48427bdb39372f89bcab16df39)
---
 doc/build-helpers/testers.chapter.md          | 49 +++++++++++++++++++
 pkgs/build-support/testers/default.nix        |  2 +
 .../testers/shellcheck/example.sh             |  3 ++
 .../testers/shellcheck/tester.nix             | 28 +++++++++++
 .../testers/shellcheck/tests.nix              | 38 ++++++++++++++
 pkgs/build-support/testers/test/default.nix   |  2 +
 6 files changed, 122 insertions(+)
 create mode 100644 pkgs/build-support/testers/shellcheck/example.sh
 create mode 100644 pkgs/build-support/testers/shellcheck/tester.nix
 create mode 100644 pkgs/build-support/testers/shellcheck/tests.nix

diff --git a/doc/build-helpers/testers.chapter.md b/doc/build-helpers/testers.chapter.md
index 34cfc00a4953..9b2dbcd8365d 100644
--- a/doc/build-helpers/testers.chapter.md
+++ b/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.
diff --git a/pkgs/build-support/testers/default.nix b/pkgs/build-support/testers/default.nix
index dbf9a6d6cb05..f70b54461141 100644
--- a/pkgs/build-support/testers/default.nix
+++ b/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 { };
 }
diff --git a/pkgs/build-support/testers/shellcheck/example.sh b/pkgs/build-support/testers/shellcheck/example.sh
new file mode 100644
index 000000000000..7e89bf37d3cc
--- /dev/null
+++ b/pkgs/build-support/testers/shellcheck/example.sh
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+echo $@
diff --git a/pkgs/build-support/testers/shellcheck/tester.nix b/pkgs/build-support/testers/shellcheck/tester.nix
new file mode 100644
index 000000000000..66f048f23095
--- /dev/null
+++ b/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
+  '';
+}
diff --git a/pkgs/build-support/testers/shellcheck/tests.nix b/pkgs/build-support/testers/shellcheck/tests.nix
new file mode 100644
index 000000000000..855aa14afead
--- /dev/null
+++ b/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
+  '';
+}
diff --git a/pkgs/build-support/testers/test/default.nix b/pkgs/build-support/testers/test/default.nix
index a815fe63e416..d719b0f349e4 100644
--- a/pkgs/build-support/testers/test/default.nix
+++ b/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, ... }: {