@hybridlabor-api/aos 4.8.0 → 4.9.0

package/skills/global_config/bash-script-validator/scripts/shellcheck_wrapper.sh

@@ -0,0 +1,174 @@
+#!/usr/bin/env bash
+#
+# ShellCheck Wrapper with Temporary Virtual Environment
+#
+# This script creates a temporary Python virtual environment, installs shellcheck-py,
+# runs shellcheck, and cleans up afterwards.
+#
+# Usage: ./shellcheck_wrapper.sh [shellcheck-options] <script-file>
+#
+
+set -euo pipefail
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Configuration
+VENV_DIR=""
+CLEANUP_ON_EXIT=true
+CACHE_VENV=false
+VENV_CACHE_DIR="${HOME}/.cache/bash-script-validator/shellcheck-venv"
+
+# Cleanup function
+cleanup() {
+    if [[ "$CLEANUP_ON_EXIT" == "true" ]] && [[ -n "$VENV_DIR" ]] && [[ -d "$VENV_DIR" ]]; then
+        echo -e "${BLUE}[INFO]${NC} Cleaning up temporary virtual environment..." >&2
+        rm -rf "$VENV_DIR"
+    fi
+}
+
+trap cleanup EXIT INT TERM
+
+# Check if Python 3 is available
+check_python() {
+    if ! command -v python3 &>/dev/null; then
+        echo -e "${RED}[ERROR]${NC} python3 not found. Please install Python 3." >&2
+        exit 1
+    fi
+}
+
+# Check if shellcheck is already available system-wide
+check_system_shellcheck() {
+    if command -v shellcheck &>/dev/null; then
+        # ShellCheck is available, use it directly
+        shellcheck "$@"
+        exit $?
+    fi
+}
+
+# Create and activate virtual environment
+setup_venv() {
+    if [[ "$CACHE_VENV" == "true" ]] && [[ -d "$VENV_CACHE_DIR" ]]; then
+        echo -e "${GREEN}[INFO]${NC} Using cached virtual environment..." >&2
+        VENV_DIR="$VENV_CACHE_DIR"
+        CLEANUP_ON_EXIT=false
+        return 0
+    fi
+
+    echo -e "${BLUE}[INFO]${NC} Creating temporary virtual environment..." >&2
+
+    if [[ "$CACHE_VENV" == "true" ]]; then
+        mkdir -p "$(dirname "$VENV_CACHE_DIR")"
+        VENV_DIR="$VENV_CACHE_DIR"
+        CLEANUP_ON_EXIT=false
+    else
+        VENV_DIR=$(mktemp -d -t shellcheck-venv.XXXXXX)
+    fi
+
+    python3 -m venv "$VENV_DIR"
+
+    # Activate virtual environment
+    # shellcheck source=/dev/null
+    source "$VENV_DIR/bin/activate"
+}
+
+# Install shellcheck-py
+install_shellcheck() {
+    local marker_file="$VENV_DIR/.shellcheck_installed"
+
+    if [[ -f "$marker_file" ]]; then
+        echo -e "${GREEN}[INFO]${NC} ShellCheck already installed in cached venv" >&2
+        return 0
+    fi
+
+    echo -e "${BLUE}[INFO]${NC} Installing shellcheck-py..." >&2
+
+    # Upgrade pip first (suppress output)
+    pip3 install --upgrade pip &>/dev/null
+
+    # Install shellcheck-py
+    if pip3 install shellcheck-py &>/dev/null; then
+        echo -e "${GREEN}[INFO]${NC} ShellCheck installed successfully" >&2
+        touch "$marker_file"
+        return 0
+    else
+        echo -e "${RED}[ERROR]${NC} Failed to install shellcheck-py" >&2
+        return 1
+    fi
+}
+
+# Run shellcheck
+run_shellcheck() {
+    if [[ ! -f "$VENV_DIR/bin/shellcheck" ]]; then
+        echo -e "${RED}[ERROR]${NC} ShellCheck binary not found in virtual environment" >&2
+        exit 1
+    fi
+
+    # Run shellcheck with all provided arguments
+    "$VENV_DIR/bin/shellcheck" "$@"
+}
+
+# Main function
+main() {
+    # If no arguments, show usage
+    if [[ $# -eq 0 ]]; then
+        echo "Usage: $0 [--cache] [--no-cache] [shellcheck-options] <script-file>"
+        echo ""
+        echo "Options:"
+        echo "  --cache      Cache the virtual environment for faster subsequent runs"
+        echo "  --no-cache   Don't use cached venv (default)"
+        echo "  --clear-cache Clear the cached virtual environment"
+        echo ""
+        echo "Examples:"
+        echo "  $0 script.sh"
+        echo "  $0 --cache -s bash script.sh"
+        echo "  $0 -f gcc script.sh"
+        exit 0
+    fi
+
+    # Parse wrapper-specific options
+    local args=()
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --cache)
+                CACHE_VENV=true
+                shift
+                ;;
+            --no-cache)
+                CACHE_VENV=false
+                shift
+                ;;
+            --clear-cache)
+                if [[ -d "$VENV_CACHE_DIR" ]]; then
+                    echo -e "${BLUE}[INFO]${NC} Clearing cached virtual environment..."
+                    rm -rf "$VENV_CACHE_DIR"
+                    echo -e "${GREEN}[INFO]${NC} Cache cleared"
+                else
+                    echo -e "${YELLOW}[INFO]${NC} No cache to clear"
+                fi
+                exit 0
+                ;;
+            *)
+                args+=("$1")
+                shift
+                ;;
+        esac
+    done
+
+    # Check if system shellcheck is available
+    check_system_shellcheck "${args[@]}"
+
+    # System shellcheck not found, use venv approach
+    check_python
+    setup_venv
+    install_shellcheck
+
+    # Run shellcheck with remaining arguments
+    run_shellcheck "${args[@]}"
+}
+
+main "$@"

package/skills/global_config/bash-script-validator/scripts/test_validate.sh

@@ -0,0 +1,446 @@
+#!/usr/bin/env bash
+#
+# Regression test suite for validate.sh
+#
+# Runs the validator against each example file and asserts the expected exit code.
+# Exit 0 when all assertions pass; non-zero otherwise.
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+readonly SCRIPT_DIR
+VALIDATOR="$SCRIPT_DIR/validate.sh"
+EXAMPLES_DIR="$SCRIPT_DIR/../examples"
+TMP_DIR="$(mktemp -d)"
+FAKE_SHELLCHECK_BIN="$TMP_DIR/fake-shellcheck-bin"
+
+cleanup() {
+    rm -rf "$TMP_DIR"
+}
+trap cleanup EXIT
+
+# Counters
+PASS=0
+FAIL=0
+
+# ─── helpers ────────────────────────────────────────────────────────────────
+
+pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
+
+# Create a deterministic shellcheck stub so regression tests do not depend on host tooling.
+mkdir -p "$FAKE_SHELLCHECK_BIN"
+cat > "$FAKE_SHELLCHECK_BIN/shellcheck" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+
+mode="${FAKE_SHELLCHECK_MODE:-ok}"
+target="${@: -1}"
+
+case "$mode" in
+    ok)
+        exit 0
+        ;;
+    warning)
+        echo "${target}:1:1: warning: fake shellcheck warning [SC9999]"
+        exit 1
+        ;;
+    infra)
+        echo "fake shellcheck infrastructure failure" >&2
+        exit 3
+        ;;
+    *)
+        echo "unknown FAKE_SHELLCHECK_MODE: $mode" >&2
+        exit 2
+        ;;
+esac
+EOF
+chmod +x "$FAKE_SHELLCHECK_BIN/shellcheck"
+
+# Run the validator and return its exit code without aborting this script.
+# Uses || to prevent set -e from treating a non-zero validator exit as fatal.
+run_validator() {
+    local file="$1"
+    shift
+
+    local exit_code=0
+    if [[ $# -gt 0 ]]; then
+        env "$@" bash "$VALIDATOR" "$file" >/dev/null 2>&1 || exit_code=$?
+    else
+        bash "$VALIDATOR" "$file" >/dev/null 2>&1 || exit_code=$?
+    fi
+    echo "$exit_code"
+}
+
+validator_output() {
+    local file="$1"
+    shift
+
+    if [[ $# -gt 0 ]]; then
+        env "$@" bash "$VALIDATOR" "$file" 2>&1 || true
+    else
+        bash "$VALIDATOR" "$file" 2>&1 || true
+    fi
+}
+
+# Assert that the validator exits with a specific code for the given file.
+assert_exit_code() {
+    local label="$1"
+    local file="$2"
+    local expected="$3"
+    shift 3
+
+    local actual
+    actual=$(run_validator "$file" "$@")
+
+    if [[ "$actual" -eq "$expected" ]]; then
+        pass "$label (exit $actual)"
+    else
+        fail "$label — expected exit $expected, got $actual"
+        # Re-run with output visible so the failure is diagnosable.
+        echo "    --- validator output ---"
+        validator_output "$file" "$@" | sed 's/^/    /'
+        echo "    --- end output ---"
+    fi
+}
+
+assert_exit_code_in() {
+    local label="$1"
+    local file="$2"
+    local expected_csv="$3"
+    shift 3
+
+    local actual
+    actual=$(run_validator "$file" "$@")
+
+    if [[ ",$expected_csv," == *",$actual,"* ]]; then
+        pass "$label (exit $actual)"
+    else
+        fail "$label — expected one of [$expected_csv], got $actual"
+        echo "    --- validator output ---"
+        validator_output "$file" "$@" | sed 's/^/    /'
+        echo "    --- end output ---"
+    fi
+}
+
+# Assert that a pattern IS found in the validator output for a given file.
+assert_output_contains() {
+    local label="$1"
+    local file="$2"
+    local pattern="$3"
+    shift 3
+
+    local output
+    output=$(validator_output "$file" "$@")
+
+    if echo "$output" | grep -qE "$pattern"; then
+        pass "$label"
+    else
+        fail "$label — pattern not found: $pattern"
+        echo "    --- validator output ---"
+        echo "$output" | sed 's/^/    /'
+        echo "    --- end output ---"
+    fi
+}
+
+# Assert that a pattern is NOT found in the validator output for a given file.
+assert_output_not_contains() {
+    local label="$1"
+    local file="$2"
+    local pattern="$3"
+    shift 3
+
+    local output
+    output=$(validator_output "$file" "$@")
+
+    if echo "$output" | grep -qE "$pattern"; then
+        fail "$label — unexpected pattern found: $pattern"
+        echo "    --- validator output ---"
+        echo "$output" | sed 's/^/    /'
+        echo "    --- end output ---"
+    else
+        pass "$label"
+    fi
+}
+
+assert_shellcheck_stage_verifiable() {
+    local label="$1"
+    local file="$2"
+    shift 2
+
+    local output
+    output=$(validator_output "$file" "$@")
+
+    if ! echo "$output" | grep -q '\[SHELLCHECK\]'; then
+        fail "$label — missing [SHELLCHECK] stage"
+        echo "    --- validator output ---"
+        echo "$output" | sed 's/^/    /'
+        echo "    --- end output ---"
+        return
+    fi
+
+    if echo "$output" | grep -qE 'ShellCheck unavailable|ShellCheck not installed'; then
+        fail "$label — ShellCheck stage unavailable"
+        echo "    --- validator output ---"
+        echo "$output" | sed 's/^/    /'
+        echo "    --- end output ---"
+        return
+    fi
+
+    if echo "$output" | grep -qE 'No ShellCheck issues found|SC[0-9]{4}|: (error|warning|note|style):'; then
+        pass "$label"
+        return
+    fi
+
+    fail "$label — ShellCheck produced no verifiable signal"
+    echo "    --- validator output ---"
+    echo "$output" | sed 's/^/    /'
+    echo "    --- end output ---"
+}
+
+# ─── test cases ─────────────────────────────────────────────────────────────
+
+echo "Running bash-script-validator tests..."
+echo ""
+
+# --- good-bash.sh: well-written bash, must exit 0 ---
+echo "[good-bash.sh]"
+assert_exit_code \
+    "exits cleanly (code 0)" \
+    "$EXAMPLES_DIR/good-bash.sh" \
+    0
+
+assert_output_not_contains \
+    "no false-positive errors" \
+    "$EXAMPLES_DIR/good-bash.sh" \
+    "✗"
+
+assert_shellcheck_stage_verifiable \
+    "shellcheck stage is verifiable" \
+    "$EXAMPLES_DIR/good-bash.sh"
+
+# --- good-shell.sh: well-written POSIX sh, must exit 0 ---
+echo ""
+echo "[good-shell.sh]"
+assert_exit_code \
+    "exits cleanly (code 0)" \
+    "$EXAMPLES_DIR/good-shell.sh" \
+    0
+
+assert_output_not_contains \
+    "no false-positive [[ ]] error from comment on line 31" \
+    "$EXAMPLES_DIR/good-shell.sh" \
+    "\[\["
+
+assert_output_not_contains \
+    "no false-positive errors" \
+    "$EXAMPLES_DIR/good-shell.sh" \
+    "✗"
+
+assert_shellcheck_stage_verifiable \
+    "shellcheck stage is verifiable" \
+    "$EXAMPLES_DIR/good-shell.sh"
+
+# --- bad-bash.sh: intentionally bad bash, must be non-clean ---
+echo ""
+echo "[bad-bash.sh]"
+assert_exit_code_in \
+    "exits non-clean (code 1 or 2)" \
+    "$EXAMPLES_DIR/bad-bash.sh" \
+    "1,2"
+
+assert_output_contains \
+    "detects eval with variable" \
+    "$EXAMPLES_DIR/bad-bash.sh" \
+    "eval with variable"
+
+assert_output_contains \
+    "detects useless cat" \
+    "$EXAMPLES_DIR/bad-bash.sh" \
+    "Useless use of cat"
+
+# --- bad-shell.sh: intentionally bad POSIX sh, must exit 2 ---
+echo ""
+echo "[bad-shell.sh]"
+assert_exit_code \
+    "exits with errors (code 2)" \
+    "$EXAMPLES_DIR/bad-shell.sh" \
+    2
+
+assert_output_contains \
+    "detects [[ ]] in sh script (line 7, actual code)" \
+    "$EXAMPLES_DIR/bad-shell.sh" \
+    "Bash-specific \[\[ \]\]"
+
+assert_output_contains \
+    "detects bash arrays in sh script" \
+    "$EXAMPLES_DIR/bad-shell.sh" \
+    "Bash-specific arrays"
+
+assert_output_contains \
+    "detects function keyword in sh script" \
+    "$EXAMPLES_DIR/bad-shell.sh" \
+    "function.*keyword"
+
+assert_output_contains \
+    "detects source command in sh script" \
+    "$EXAMPLES_DIR/bad-shell.sh" \
+    "source.*command"
+
+assert_output_contains \
+    "detects eval with variable" \
+    "$EXAMPLES_DIR/bad-shell.sh" \
+    "eval with variable"
+
+assert_output_contains \
+    "detects useless cat" \
+    "$EXAMPLES_DIR/bad-shell.sh" \
+    "Useless use of cat"
+
+# Only real code lines flagged — not comment lines for [[ check
+assert_output_not_contains \
+    "[[ check does not flag comment lines in bad-shell.sh" \
+    "$EXAMPLES_DIR/bad-shell.sh" \
+    "Line [0-9]*:# Bad: using bash-specific"
+
+# --- p1 regression fixtures ---
+INDENTED_SH="$TMP_DIR/indented-bashisms.sh"
+cat > "$INDENTED_SH" <<'EOF'
+#!/bin/sh
+set -e
+    function helper {
+        echo "bad"
+    }
+        source /etc/profile
+helper
+EOF
+
+COMMENT_ONLY_ERR_HANDLING="$TMP_DIR/comment-only-error-handling.sh"
+cat > "$COMMENT_ONLY_ERR_HANDLING" <<'EOF'
+#!/bin/sh
+# set -e
+# set -o errexit
+# trap 'echo failed' ERR
+echo "hello"
+EOF
+
+echo ""
+echo "[p1 regressions]"
+assert_output_contains \
+    "indented function in sh is detected" \
+    "$INDENTED_SH" \
+    "function.*keyword"
+
+assert_output_contains \
+    "indented source in sh is detected" \
+    "$INDENTED_SH" \
+    "source.*command"
+
+assert_output_contains \
+    "comment-only set -e does not suppress warning" \
+    "$COMMENT_ONLY_ERR_HANDLING" \
+    "Consider adding error handling"
+
+# --- p2 deterministic shellcheck stage regressions ---
+echo ""
+echo "[p2 shellcheck-mode regressions]"
+
+assert_exit_code \
+    "system mode accepts deterministic clean shellcheck run" \
+    "$EXAMPLES_DIR/good-bash.sh" \
+    0 \
+    VALIDATOR_REQUIRE_SHELLCHECK=1 \
+    VALIDATOR_SHELLCHECK_MODE=system \
+    PATH="$FAKE_SHELLCHECK_BIN:/usr/bin:/bin"
+
+assert_output_contains \
+    "system mode reports clean shellcheck output" \
+    "$EXAMPLES_DIR/good-bash.sh" \
+    "No ShellCheck issues found" \
+    VALIDATOR_REQUIRE_SHELLCHECK=1 \
+    VALIDATOR_SHELLCHECK_MODE=system \
+    PATH="$FAKE_SHELLCHECK_BIN:/usr/bin:/bin"
+
+assert_exit_code \
+    "system mode returns warning on shellcheck findings" \
+    "$EXAMPLES_DIR/good-bash.sh" \
+    1 \
+    VALIDATOR_REQUIRE_SHELLCHECK=1 \
+    VALIDATOR_SHELLCHECK_MODE=system \
+    FAKE_SHELLCHECK_MODE=warning \
+    PATH="$FAKE_SHELLCHECK_BIN:/usr/bin:/bin"
+
+assert_output_contains \
+    "system mode surfaces shellcheck issue codes" \
+    "$EXAMPLES_DIR/good-bash.sh" \
+    "SC9999" \
+    VALIDATOR_REQUIRE_SHELLCHECK=1 \
+    VALIDATOR_SHELLCHECK_MODE=system \
+    FAKE_SHELLCHECK_MODE=warning \
+    PATH="$FAKE_SHELLCHECK_BIN:/usr/bin:/bin"
+
+assert_exit_code \
+    "system mode fails on shellcheck infrastructure error" \
+    "$EXAMPLES_DIR/good-bash.sh" \
+    2 \
+    VALIDATOR_REQUIRE_SHELLCHECK=1 \
+    VALIDATOR_SHELLCHECK_MODE=system \
+    FAKE_SHELLCHECK_MODE=infra \
+    PATH="$FAKE_SHELLCHECK_BIN:/usr/bin:/bin"
+
+assert_output_contains \
+    "system mode reports shellcheck infrastructure error" \
+    "$EXAMPLES_DIR/good-bash.sh" \
+    "ShellCheck execution failed \(exit 3\)" \
+    VALIDATOR_REQUIRE_SHELLCHECK=1 \
+    VALIDATOR_SHELLCHECK_MODE=system \
+    FAKE_SHELLCHECK_MODE=infra \
+    PATH="$FAKE_SHELLCHECK_BIN:/usr/bin:/bin"
+
+assert_exit_code \
+    "invalid shellcheck mode exits with error" \
+    "$EXAMPLES_DIR/good-bash.sh" \
+    2 \
+    VALIDATOR_SHELLCHECK_MODE=invalid-mode
+
+assert_output_contains \
+    "invalid shellcheck mode prints actionable error" \
+    "$EXAMPLES_DIR/good-bash.sh" \
+    "Invalid VALIDATOR_SHELLCHECK_MODE" \
+    VALIDATOR_SHELLCHECK_MODE=invalid-mode
+
+# --- edge cases ---
+echo ""
+echo "[edge cases]"
+
+# P0: strict mode must fail when ShellCheck is unavailable
+assert_exit_code \
+    "strict mode fails when shellcheck is unavailable" \
+    "$EXAMPLES_DIR/good-bash.sh" \
+    2 \
+    VALIDATOR_REQUIRE_SHELLCHECK=1 \
+    VALIDATOR_DISABLE_SHELLCHECK=1
+
+assert_output_contains \
+    "strict mode reports shellcheck unavailable" \
+    "$EXAMPLES_DIR/good-bash.sh" \
+    "ShellCheck (unavailable|disabled by configuration)" \
+    VALIDATOR_REQUIRE_SHELLCHECK=1 \
+    VALIDATOR_DISABLE_SHELLCHECK=1
+
+# Missing file → exit 1 from the validator's own error path
+assert_exit_code \
+    "missing file exits non-zero" \
+    "/nonexistent/path/script.sh" \
+    1
+
+# ─── summary ────────────────────────────────────────────────────────────────
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+echo ""
+
+if [[ $FAIL -gt 0 ]]; then
+    exit 1
+fi