Shell
#!/bin/bash
# ============================================================================
# GITHUB WORKFLOW GUARDIAN - "The Guardian"
# ============================================================================
# A blocking hook that enforces GitHub workflow best practices before
# allowing code changes. Prevents common build failures like:
# - Missing module imports
# - Components with non-existent dependencies
# - Direct pushes to protected branches
# - Commits with missing/failing builds
#
# Part of: ID8Pipeline Quality Enforcement System
# Author: ID8Labs
# Version: 1.0.0
#
# BLOCKING ISSUES (exit 2):
# - CRITICAL: Missing imports/modules that would break build
# - ERROR: Working on protected branch
# - WARNING: TypeScript errors in modified files
#
# NON-BLOCKING (exit 0 with warning):
# - INFO: Uncommitted changes, suggested improvements
#
# Usage: Triggered automatically via PostToolUse hook on Edit|Write
# ============================================================================
set -uo pipefail
# Read input from stdin (Claude Code hook format)
INPUT=$(cat)
# Extract file path from tool input
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
# If no file path, try to get from positional arg
if [[ -z "$FILE_PATH" ]]; then
FILE_PATH="${1:-}"
fi
# Exit if no file path or not a code file
if [[ -z "$FILE_PATH" || ! -f "$FILE_PATH" ]]; then
exit 0
fi
# Get file extension
FILE_EXT="${FILE_PATH##*.}"
# Only check TypeScript/JavaScript files
case "$FILE_EXT" in
ts|tsx|js|jsx)
;;
*)
exit 0
;;
esac
# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
CYAN='\033[0;36m'
NC='\033[0m'
log() { echo -e "${CYAN}[GUARDIAN]${NC} $1"; }
warn() { echo -e "${YELLOW}[WARNING]${NC} $1"; }
error() { echo -e "${RED}[ERROR]${NC} $1"; }
pass() { echo -e "${GREEN}[PASS]${NC} $1"; }
block() { echo -e "${RED}[BLOCKED]${NC} $1"; }
BLOCKING_ISSUES=0
WARNINGS=0
REVIEW_REPORT=""
add_issue() {
local severity="$1"
local message="$2"
REVIEW_REPORT="${REVIEW_REPORT}\n - [$severity] $message"
if [[ "$severity" == "CRITICAL" || "$severity" == "ERROR" ]]; then
BLOCKING_ISSUES=$((BLOCKING_ISSUES + 1))
else
WARNINGS=$((WARNINGS + 1))
fi
}
# Get working directory from file path
WORK_DIR=$(dirname "$FILE_PATH")
while [[ ! -f "$WORK_DIR/package.json" && "$WORK_DIR" != "/" ]]; do
WORK_DIR=$(dirname "$WORK_DIR")
done
if [[ ! -f "$WORK_DIR/package.json" ]]; then
# Not in a Node.js project
exit 0
fi
cd "$WORK_DIR" || exit 0
log "Checking: $FILE_PATH"
# ==========================================
# 1. IMPORT RESOLUTION CHECK
# ==========================================
# This is the key check that would have caught NorthStarConsole
log "Validating imports..."
# Extract imports from the file
IMPORTS=$(grep -E "^import .* from ['\"](@/|\.\.?/)" "$FILE_PATH" 2>/dev/null || true)
if [[ -n "$IMPORTS" ]]; then
while IFS= read -r import_line; do
# Extract the path from the import
IMPORT_PATH=$(echo "$import_line" | sed -n "s/.*from ['\"]\\([^'\"]*\\)['\"].*/\\1/p")
if [[ -z "$IMPORT_PATH" ]]; then
continue
fi
# Resolve @/ paths to src/
if [[ "$IMPORT_PATH" == @/* ]]; then
RESOLVED_PATH="src/${IMPORT_PATH#@/}"
else
# Relative path
FILE_DIR=$(dirname "$FILE_PATH")
RESOLVED_PATH="$FILE_DIR/$IMPORT_PATH"
fi
# Check if import exists
FOUND=false
for ext in "" ".ts" ".tsx" ".js" ".jsx" "/index.ts" "/index.tsx" "/index.js"; do
CHECK_PATH="${RESOLVED_PATH}${ext}"
if [[ -f "$CHECK_PATH" ]]; then
FOUND=true
break
fi
done
if [[ "$FOUND" == false ]]; then
# This is critical - would break the build
add_issue "CRITICAL" "Missing module: $IMPORT_PATH"
# Special message for stores
if [[ "$IMPORT_PATH" == *"stores/"* ]]; then
STORE_NAME=$(basename "$IMPORT_PATH")
REVIEW_REPORT="${REVIEW_REPORT}\n π‘ Store '$STORE_NAME' does not exist. Create it first!"
fi
fi
done <<< "$IMPORTS"
fi
# ==========================================
# 2. TYPESCRIPT QUICK CHECK
# ==========================================
if [[ -f "tsconfig.json" ]]; then
log "Running TypeScript check..."
# Quick type check on the specific file's related modules
TSC_OUTPUT=$(npx tsc --noEmit --skipLibCheck 2>&1 | grep -E "error TS" | head -5 || true)
if [[ -n "$TSC_OUTPUT" ]]; then
# Check if errors are in the modified file
if echo "$TSC_OUTPUT" | grep -q "$(basename "$FILE_PATH")"; then
add_issue "ERROR" "TypeScript errors in modified file"
REVIEW_REPORT="${REVIEW_REPORT}\n $(echo "$TSC_OUTPUT" | head -3)"
fi
else
pass "TypeScript: Clean"
fi
fi
# ==========================================
# 3. BRANCH PROTECTION CHECK
# ==========================================
if git rev-parse --git-dir > /dev/null 2>&1; then
CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
if [[ "$CURRENT_BRANCH" == "main" || "$CURRENT_BRANCH" == "master" || "$CURRENT_BRANCH" == "develop" ]]; then
add_issue "ERROR" "Modifying code on protected branch '$CURRENT_BRANCH'"
REVIEW_REPORT="${REVIEW_REPORT}\n π‘ Create a feature branch: git checkout -b feature/<name>"
fi
fi
# ==========================================
# 4. LAYOUT/CRITICAL COMPONENT WARNING
# ==========================================
if [[ "$FILE_PATH" == *"components/layout/"* || "$FILE_PATH" == *"/app/"* ]]; then
warn "Modifying critical component - build verification recommended"
add_issue "INFO" "Critical path modification: run 'npm run build' before commit"
fi
# ==========================================
# 5. OUTPUT REVIEW
# ==========================================
echo ""
echo "βββββββββββββββββββββββββββββββββββββββββββββββββββββββ"
echo "GITHUB WORKFLOW GUARDIAN"
echo "βββββββββββββββββββββββββββββββββββββββββββββββββββββββ"
if [[ $BLOCKING_ISSUES -eq 0 && $WARNINGS -eq 0 ]]; then
pass "All workflow checks passed!"
echo ""
exit 0
elif [[ $BLOCKING_ISSUES -eq 0 ]]; then
warn "Found $WARNINGS warning(s):"
echo -e "$REVIEW_REPORT"
echo ""
echo "βΉοΈ Non-blocking - proceeding with caution"
echo "βββββββββββββββββββββββββββββββββββββββββββββββββββββββ"
exit 0
else
error "Found $BLOCKING_ISSUES blocking issue(s):"
echo -e "$REVIEW_REPORT"
echo ""
echo "π βββββββββββββββββββββββββββββββββββββββββββββββββββββββ"
echo " BLOCKED: Fix these issues before proceeding"
echo ""
echo " This prevents build failures in CI/CD pipeline."
echo ""
if echo "$REVIEW_REPORT" | grep -q "Missing module"; then
echo " To fix missing imports:"
echo " 1. Create the missing module/store, OR"
echo " 2. Remove the import from this file"
fi
if echo "$REVIEW_REPORT" | grep -q "protected branch"; then
echo " To fix branch issue:"
echo " 1. Stash changes: git stash"
echo " 2. Create branch: git checkout -b feature/<name>"
echo " 3. Pop changes: git stash pop"
fi
echo "βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ"
# Exit code 2 = blocking error
exit 2
fi