From c72878c8d0d0383d2d4d2aed8532ccd4301bf93e Mon Sep 17 00:00:00 2001
From: Leynos <leynos@troubledskies.net>
Date: Wed, 6 Aug 2025 01:28:35 +0100
Subject: [PATCH 1/2] Extract unused artefact assertion into script

---
 .github/workflows/netsukefile-test.yml | 16 +++++++++++++---
 scripts/assert-file-absent.sh          | 23 +++++++++++++++++++++++
 scripts/assert-file-exists.sh          |  9 ++++++++-
 3 files changed, 44 insertions(+), 4 deletions(-)
 create mode 100755 scripts/assert-file-absent.sh

diff --git a/.github/workflows/netsukefile-test.yml b/.github/workflows/netsukefile-test.yml
index 761f1b6b..f6a945e3 100644
--- a/.github/workflows/netsukefile-test.yml
+++ b/.github/workflows/netsukefile-test.yml
@@ -51,18 +51,28 @@ jobs:
               command: "touch unused.txt"
           MANIFEST
       - name: Build dependent and inline targets
-        run: ./target/debug/netsuke --verbose build dependent.txt inline-command.txt inline-script.txt
+        run: ./target/debug/netsuke --verbose build --emit build.ninja dependent.txt inline-command.txt inline-script.txt
       - name: Assert dependent artefacts exist
+        env:
+          NINJA_MANIFEST: build.ninja
         run: |
           scripts/assert-file-exists.sh base.txt
           scripts/assert-file-exists.sh dependent.txt
       - name: Assert inline command artefact exists
+        env:
+          NINJA_MANIFEST: build.ninja
         run: scripts/assert-file-exists.sh inline-command.txt
       - name: Assert inline script artefact exists
+        env:
+          NINJA_MANIFEST: build.ninja
         run: scripts/assert-file-exists.sh inline-script.txt
       - name: Run action target
-        run: ./target/debug/netsuke --verbose build say-hello
+        run: ./target/debug/netsuke --verbose build --emit action.ninja say-hello
       - name: Assert action artefact exists
+        env:
+          NINJA_MANIFEST: action.ninja
         run: scripts/assert-file-exists.sh action-called.txt
       - name: Assert unused action artefact absent
-        run: test ! -f unused.txt
+        env:
+          NINJA_MANIFEST: action.ninja
+        run: scripts/assert-file-absent.sh unused.txt
diff --git a/scripts/assert-file-absent.sh b/scripts/assert-file-absent.sh
new file mode 100755
index 00000000..8fabbdd3
--- /dev/null
+++ b/scripts/assert-file-absent.sh
@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Ensures the Netsuke build did not produce an unexpected artefact.
+# If the artefact is present and `NINJA_MANIFEST` is set, the referenced
+# Ninja manifest is dumped to stderr for debugging.
+set -euo pipefail
+
+if [[ $# -ne 1 ]]; then
+  echo "Usage: $(basename "$0") <file>" >&2
+  exit 64   # EX_USAGE
+fi
+
+file="$1"
+
+if [[ -f "$file" ]]; then
+  echo "Unexpected build artefact '$file' present." >&2
+  if [[ -n "${NINJA_MANIFEST:-}" && -f "$NINJA_MANIFEST" ]]; then
+    echo "Ninja manifest '$NINJA_MANIFEST' for debugging:" >&2
+    echo "-----BEGIN NINJA MANIFEST-----" >&2
+    cat "$NINJA_MANIFEST" >&2
+    echo "-----END NINJA MANIFEST-----" >&2
+  fi
+  exit 1
+fi
diff --git a/scripts/assert-file-exists.sh b/scripts/assert-file-exists.sh
index 82c9d2ed..7c7f0c76 100755
--- a/scripts/assert-file-exists.sh
+++ b/scripts/assert-file-exists.sh
@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 # Ensures the Netsuke build produced the expected artefact.
-# Fails fast if the given file is missing.
+# If the artefact is absent and `NINJA_MANIFEST` is set, the referenced
+# Ninja manifest is dumped to stderr for debugging.
 set -euo pipefail
 
 if [[ $# -ne 1 ]]; then
@@ -12,5 +13,11 @@ file="$1"
 
 if [[ ! -f "$file" ]]; then
   echo "Expected build artefact '$file' to exist." >&2
+  if [[ -n "${NINJA_MANIFEST:-}" && -f "$NINJA_MANIFEST" ]]; then
+    echo "Ninja manifest '$NINJA_MANIFEST' for debugging:" >&2
+    echo "-----BEGIN NINJA MANIFEST-----" >&2
+    cat "$NINJA_MANIFEST" >&2
+    echo "-----END NINJA MANIFEST-----" >&2
+  fi
   exit 1
 fi

From 44d65768ec66aaf7f86e127c2e227c874ce2be09 Mon Sep 17 00:00:00 2001
From: Leynos <leynos@troubledskies.net>
Date: Wed, 6 Aug 2025 07:59:20 +0100
Subject: [PATCH 2/2] Use widely recognized exit code 2 for usage errors

Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>
---
 scripts/assert-file-absent.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/assert-file-absent.sh b/scripts/assert-file-absent.sh
index 8fabbdd3..eb3cb6c3 100755
--- a/scripts/assert-file-absent.sh
+++ b/scripts/assert-file-absent.sh
@@ -6,7 +6,7 @@ set -euo pipefail
 
 if [[ $# -ne 1 ]]; then
   echo "Usage: $(basename "$0") <file>" >&2
-  exit 64   # EX_USAGE
+  exit 2   # usage error
 fi
 
 file="$1"