feat(M2): Documentation flow, accuracy, consistency cleanup, and cross-platform shell portability

scripts/lib/portable.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# portable.sh — POSIX-safe helper functions for BSD/GNU shell portability
+#
+# Source this file in scripts that need cross-platform variants of:
+#   - stat(1)  — BSD uses -f, GNU uses -c
+#
+# Usage:
+#   source "$(dirname "${BASH_SOURCE[0]}")/portable.sh"
+#   portable_stat_perms "$file"   # -> octal permissions string, e.g. "755"
+#
+# Supported platforms:
+#   - macOS (BSD stat)
+#   - Linux/Ubuntu (GNU stat)
+
+# portable_stat_perms <path>
+# Outputs the file's permission bits as an octal string (e.g. "755").
+# Exits non-zero if stat fails.
+portable_stat_perms() {
+  local path="$1"
+  case "$(uname -s)" in
+    Darwin)
+      stat -f '%Lp' "$path"
+      ;;
+    *)
+      stat -c '%a' "$path"
+      ;;
+  esac
+}

scripts/lib/run-shellcheck.mjs

@@ -132,7 +132,7 @@ console.log(`shellcheck: scanning ${files.length} file(s)…`);
 
 let failures = 0;
 for (const file of files.sort()) {
-  const result = spawnSync("shellcheck", [file], {
+  const result = spawnSync("shellcheck", ["-x", "--source-path=SCRIPTDIR", file], {
     encoding: "utf8",
     stdio: ["ignore", "pipe", "pipe"],
   });