refactor: make shared message functions reusable

.github/workflows/linter.yml

@@ -18,6 +18,9 @@
   jobs:
     run-lint:
       runs-on: ubuntu-latest
+      permissions:
+        contents: read
+        statuses: write
       steps:
         - name: Checkout code
           uses: actions/checkout@v6

README.md

@@ -49,6 +49,41 @@ To install the dotfiles, clone this repository to your 🏠 📂 and then 🏃 t
 
 Once you complete the installation steps, you will see a welcome message 📜.
 
+## Messages in scripts and containers
+
+The shared message functions live in `src/bash/messages`. A script can load
+this file to use the existing colours and timestamps without running terminal
+setup or creating directories:
+
+```bash
+source "$HOME/dotfiles/src/bash/messages"
+msg info "Starting the tests."
+kmsg "The tests passed."
+wmsg "A dependency is missing."
+emsg "The tests failed."
+```
+
+`msg` accepts `fail`, `ok`, `warn`, or `info` followed by the message. Passing
+only a message prints a notice. The shortcuts `emsg`, `kmsg`, `wmsg`, and
+`imsg` keep their existing meanings. Message text, spacing, colours, and the
+`America/St_Lucia` timestamp timezone are unchanged.
+
+The regular `src/bash/functions` file loads these same definitions. Existing
+terminal configuration therefore keeps using the same function names. The
+`ptc` alias remains the existing pytest command.
+
+To check an unpublished checkout, run these commands from its repository root:
+
+```bash
+bash -c 'source ./src/bash/messages; imsg "Shared messages loaded."; kmsg "Bash check complete."'
+zsh -f -c 'source ./src/bash/messages; imsg "Shared messages loaded."; kmsg "Zsh check complete."'
+```
+
+Use direct sourcing while testing a feature branch: `install` and `update`
+select the `production` branch. For containers, include a reviewed dotfiles
+revision containing this file in the image and explicitly source the file in
+the script. A noninteractive script should not depend on `.bashrc` being read.
+
 ## Uninstallation
 
 To uninstall the dotfiles, run the following commands:
@@ -100,6 +135,7 @@ Here is the dotfiles's directory structure (note that Zsh uses the bash function
     |--- bash
         |--- aliases
         |--- functions
+        |--- messages
         |--- env.env
     |--- zsh
         |--- aliases

src/bash/functions

@@ -1,39 +1,15 @@
 #!/usr/bin/env bash
 
 
-# Print color coded messages
-msg() {
-  timestamp=$(TZ="America/St_Lucia" date '+%Y-%m-%d %H:%M:%S')
-  case $1 in
-    fail)
-      printf "\n%s  \033[1;31m[  FAILURE  ]\033[0m %s\n\n" "$timestamp" "$2"
-      ;;
-    ok)
-      printf "\n%s  \033[1;32m[  SUCCESS  ]\033[0m %s\n\n" "$timestamp" "$2"
-      ;;
-    warn)
-      printf "\n%s  \033[1;33m[  WARNING  ]\033[0m %s\n\n" "$timestamp" "$2"
-      ;;
-    info)
-      printf "\n%s  \033[1;34m[INFORMATION]\033[0m %s\n\n" "$timestamp" "$2"
-      ;;
-    *)
-      printf "\n%s  [  NOTICE  ] %s\n\n"  "$timestamp" "$1"
-      ;;
-  esac
-}
-emsg() {
-  msg "fail" "$1"
-}
-kmsg() {
-  msg "ok" "$1"
-}
-imsg() {
-  msg "info" "$1"
-}
-wmsg() {
-  msg "warn" "$1"
-}
+# Load messages from this checkout in either Bash or Zsh.
+if [ -n "${ZSH_VERSION:-}" ]; then
+  # ShellCheck parses this as Bash; only Zsh evaluates this expansion.
+  # shellcheck disable=SC2296,SC2298,SC1091
+  source "${${(%):-%x}:A:h}/messages" || return
+else
+  # shellcheck source=src/bash/messages
+  source "$(dirname -- "${BASH_SOURCE[0]}")/messages" || return
+fi
 
 
 # A greeting script

src/bash/messages

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+
+# Shared message functions. Sourcing this file performs no terminal setup.
+# Print color coded messages
+msg() {
+  timestamp=$(TZ="America/St_Lucia" date '+%Y-%m-%d %H:%M:%S')
+  case $1 in
+    fail)
+      printf "\n%s  \033[1;31m[  FAILURE  ]\033[0m %s\n\n" "$timestamp" "$2"
+      ;;
+    ok)
+      printf "\n%s  \033[1;32m[  SUCCESS  ]\033[0m %s\n\n" "$timestamp" "$2"
+      ;;
+    warn)
+      printf "\n%s  \033[1;33m[  WARNING  ]\033[0m %s\n\n" "$timestamp" "$2"
+      ;;
+    info)
+      printf "\n%s  \033[1;34m[INFORMATION]\033[0m %s\n\n" "$timestamp" "$2"
+      ;;
+    *)
+      printf "\n%s  [  NOTICE  ] %s\n\n"  "$timestamp" "$1"
+      ;;
+  esac
+}
+emsg() {
+  msg "fail" "$1"
+}
+kmsg() {
+  msg "ok" "$1"
+}
+imsg() {
+  msg "info" "$1"
+}
+wmsg() {
+  msg "warn" "$1"
+}