docs: add technical docstring to pr-check-test-files.sh

.github/scripts/pr-check-test-files.sh

@@ -1,4 +1,41 @@
 #!/usr/bin/env bash
+set -euo pipefail
+
+# ======================================================================================================================================================
+# @file: pr-check-test-files.sh
+#
+# @Description A CI check written in bash that enforces the '_test.py' suffix to ensure Pytest can automatically discover 
+#               new or renamed test files in a Pull Request. 
+# 
+# @logic: 
+# 1. Identifies files as (A) Added, (R) Renamed, or (C) Copied using 'git diff' to check 
+#    relevant filename ($file1 for added files, $file2 for renamed/copied files). 
+# 2. Validates paths against allowed test directories (unit/integration).
+# 3. Excludes specific utility (ex., conftest.py, utils.py) and non-Python files.
+# 4. Parses tab-separated Git output via IFS=$'\t' to ensure robust filename handling.
+# 5. Routes files using case statement based on git status
+#
+# @types:
+# - String: Used for file paths and git status codes. 
+# - Array: Used for 'TEST_DIRS', 'EXCEPTION_NAMES', and accumulating errors.
+#
+# @Parameters:
+# - None: This script does not accept CLI arguments. It derives the input from the current Git state compared against origin/main.
+#  
+# @Dependencies:
+# - Git: (for diff)
+# - Bash: (runs the script)
+# - Pytest: (naming standard)
+#
+# @Permissions:
+# - Requires Execute permissions (chmod +x) to run. Also needs Read access to the git repository to perform the diff.
+#
+# @Return
+# - 0: All test files follow the naming standard.
+# - 1: Exits with status 1 and outputs error messages in red.
+#      Includes a yellow instructional block providing reason why the file failed.
+# ======================================================================================================================================================
+
 RED="\033[31m"
 YELLOW="\033[33m"
 RESET="\033[0m"

CHANGELOG.md

@@ -89,6 +89,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - Improved unit test coverage for `TransactionId` class, covering parsing logic, hashing, and scheduled transactions.
 - Chained Good First Issue assignment with mentor assignment to bypass GitHub's anti-recursion protection - mentor assignment now occurs immediately after successful user assignment in the same workflow execution. (#1369)
 - Add GitHub Actions script and workflow for automatic spam list updates.
+- Added technical docstrings and hardening (set -euo pipefail) to the pr-check-test-files.sh script (#1336)
 
 ### Changed
 - Added global review instructions to CodeRabbit configuration to limit reviews to issue/PR scope and prevent scope creep [#1373]