From 657fb0007f39f07cc0401e0c5d03e25df6234aa4 Mon Sep 17 00:00:00 2001
From: Alexander M Pickering <alex@cogarr.net>
Date: Tue, 21 Jul 2026 20:19:46 -0500
Subject: Inital commit.

---
 scripts/lib/trace-init.sh | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)
 create mode 100644 scripts/lib/trace-init.sh

(limited to 'scripts/lib/trace-init.sh')

diff --git a/scripts/lib/trace-init.sh b/scripts/lib/trace-init.sh
new file mode 100644
index 0000000..80f1ab0
--- /dev/null
+++ b/scripts/lib/trace-init.sh
@@ -0,0 +1,42 @@
+# scripts/lib/trace-init.sh
+# Instrumentation hook sourced automatically by every non-interactive bash
+# invocation via the BASH_ENV environment variable.
+#
+# The bats suite runs the tool with `bash "$TRBLDOC"`, so exporting
+# BASH_ENV=<this file> causes each trbldoc.sh process to enable xtrace at
+# startup WITHOUT modifying trbldoc.sh or the test files. The emitted trace is
+# consumed by the coverage and hotspot aggregators.
+#
+# Activated only when TRBLDOC_TRACE_DIR is set, and only for scripts whose
+# basename appears in TRBLDOC_TRACE_TARGETS (default: trbldoc.sh). This keeps
+# unrelated bash helpers (md2html stub, bats internals) out of the trace.
+#
+# TRBLDOC_TRACE_MODE selects the PS4 format:
+#   cov   -> "<marker> <source>:<lineno>"                 (line coverage)
+#   time  -> "<marker> <source>:<lineno> <EPOCHREALTIME>" (line timing; bash>=5)
+#
+# Every traced line is prefixed with the marker token @@TBL@@. bash repeats the
+# FIRST PS4 character once per call-nesting level, so the aggregators match the
+# marker with a tolerant pattern rather than a fixed prefix.
+
+if [ -n "${TRBLDOC_TRACE_DIR:-}" ]; then
+  __tb_self="$0"
+  __tb_base="${__tb_self##*/}"
+  case " ${TRBLDOC_TRACE_TARGETS:-trbldoc.sh} " in
+    *" ${__tb_base} "*)
+      # Dedicated append fd per process; PID keeps parallel xargs workers apart.
+      __tb_trace_file="${TRBLDOC_TRACE_DIR}/trace.$$.log"
+      # shellcheck disable=SC3023
+      exec 7>>"$__tb_trace_file"
+      export BASH_XTRACEFD=7
+      if [ "${TRBLDOC_TRACE_MODE:-cov}" = "time" ]; then
+        # EPOCHREALTIME is bash>=5; used only for the hotspot profiler.
+        PS4='@@TBL@@ ${BASH_SOURCE}:${LINENO} ${EPOCHREALTIME} '
+      else
+        PS4='@@TBL@@ ${BASH_SOURCE}:${LINENO} '
+      fi
+      export PS4
+      set -x
+      ;;
+  esac
+fi
-- 
cgit v1.2.3-70-g09d2