guardian-framework 0.1.0

package/templates/pi/scripts/languages/go/validate-tests.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-tests.sh — Go
+# ============================================================================
+set -euo pipefail
+
+ERRORS=()
+WARNINGS=()
+PASS_COUNT=0
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+pass() { echo -e "${GREEN}✅ PASS${NC} $1"; PASS_COUNT=$((PASS_COUNT + 1)); }
+fail() { echo -e "${RED}❌ FAIL${NC} $1"; ERRORS+=("$1"); }
+warn() { echo -e "${YELLOW}⚠️  WARN${NC} $1"; WARNINGS+=("$1"); }
+
+echo "============================================"
+echo "  Test Validation (Go)"
+echo "============================================"
+echo ""
+
+# ---------------------------------------------------------------------------
+# Unit Tests
+# ---------------------------------------------------------------------------
+echo "--- Unit Tests ---"
+if [ -f "go.mod" ]; then
+    # Prefer internal/ and pkg/ if they exist; fall back to ./...
+    if [ -d "internal" ] || [ -d "pkg" ]; then
+        TEST_PATHS=""
+        [ -d "internal" ] && TEST_PATHS="./internal/..."
+        [ -d "pkg" ] && TEST_PATHS="${TEST_PATHS:+$TEST_PATHS }./pkg/..."
+        if go test ${TEST_PATHS} -count=1 -v 2>/dev/null; then
+            pass "Unit tests passed"
+        else
+            fail "Unit tests failed"
+        fi
+    else
+        if go test ./... -count=1 -v 2>/dev/null; then
+            pass "Unit tests passed"
+        else
+            fail "Unit tests failed"
+        fi
+    fi
+else
+    pass "No go.mod (skipping unit tests)"
+fi
+
+# ---------------------------------------------------------------------------
+# Integration Tests
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Integration Tests ---"
+if [ -f "go.mod" ]; then
+    HAS_INTEGRATION=false
+    if [ -d "tests/integration" ]; then
+        HAS_INTEGRATION=true
+    fi
+    # Also check for _test.go files with build tag "integration"
+    if grep -rl '//go:build integration' --include="*_test.go" . 2>/dev/null | grep -q .; then
+        HAS_INTEGRATION=true
+    fi
+    if [ "$HAS_INTEGRATION" = true ]; then
+        if go test -tags=integration ./... -count=1 -v 2>/dev/null; then
+            pass "Integration tests passed"
+        else
+            fail "Integration tests failed"
+        fi
+    else
+        pass "No integration tests found (skipped)"
+    fi
+else
+    pass "No go.mod (skipping integration tests)"
+fi
+
+# ---------------------------------------------------------------------------
+# Coverage
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Coverage ---"
+if [ -f "go.mod" ]; then
+    COVERAGE_OUTPUT=$(go test -coverprofile=coverage.out ./... 2>&1 || true)
+    if [ -f "coverage.out" ]; then
+        COVERAGE_PCT=$(go tool cover -func=coverage.out 2>/dev/null | grep "^total:" | awk '{print $3}' | tr -d '%' || echo "0")
+        if [ -z "$COVERAGE_PCT" ] || [ "$COVERAGE_PCT" = "0.0" ]; then
+            COVERAGE_PCT="0"
+        fi
+        # Compare coverage percentage (use awk for float comparison)
+        MEETS_THRESHOLD=$(echo "$COVERAGE_PCT" | awk '{if ($1 >= 80) print 1; else print 0}')
+        if [ "$MEETS_THRESHOLD" -eq 1 ]; then
+            pass "Coverage: ${COVERAGE_PCT}% (≥ 80%)"
+        else
+            fail "Coverage: ${COVERAGE_PCT}% (< 80%)"
+        fi
+        rm -f coverage.out
+    else
+        warn "No coverage output generated"
+    fi
+else
+    warn "go.mod not found, skipping coverage"
+fi
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+echo ""
+echo "============================================"
+echo "  Summary"
+echo "============================================"
+echo -e "  Passed:   ${GREEN}${PASS_COUNT}${NC}"
+echo -e "  Failed:   ${RED}${#ERRORS[@]}${NC}"
+echo ""
+
+if [ ${#ERRORS[@]} -gt 0 ]; then
+    echo "FAILURES:"
+    for err in "${ERRORS[@]}"; do
+        echo "  - $err"
+    done
+    exit 1
+fi
+
+echo -e "${GREEN}Test validation passed.${NC}"
+exit 0

package/templates/pi/scripts/languages/java/validate-annotations.sh

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-annotations.sh — Spring Boot Annotation Enforcement
+# ============================================================================
+# Checks:
+#   1. @Transactional on @Service public methods
+#   2. @PostConstruct allowed only in service/config/component packages
+#   3. Field injection (@Autowired on fields) — constructor injection required
+#   4. Layering: web/ must not import repository/ directly
+#   5. Package naming: enforce com.{project}.{layer}.{component}
+# ============================================================================
+set -euo pipefail
+
+PASS_COUNT=0; ERRORS=(); WARNINGS=()
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
+pass() { echo -e "${GREEN}✅ PASS${NC} $1"; PASS_COUNT=$((PASS_COUNT + 1)); }
+fail() { echo -e "${RED}❌ FAIL${NC} $1"; ERRORS+=("$1"); }
+warn() { echo -e "${YELLOW}⚠️  WARN${NC} $1"; WARNINGS+=("$1"); }
+
+echo "============================================"
+echo "  Spring Annotation Validation"
+echo "============================================"
+echo ""
+
+SRC_DIR="${1:-src/main/java}"
+
+# ============================================================================
+# Check 1: @Transactional on @Service public methods
+# ============================================================================
+echo "--- @Transactional Coverage ---"
+if [ -d "$SRC_DIR" ]; then
+    SERVICE_FILES=$(find "$SRC_DIR" -name "*.java" -exec grep -l "@Service" {} \; 2>/dev/null)
+    if [ -n "$SERVICE_FILES" ]; then
+        MISSING_TRANSACTIONAL=0
+        for f in $SERVICE_FILES; do
+            # Find public methods in @Service classes
+            PUBLIC_METHODS=$(grep -c "public\s" "$f" 2>/dev/null || echo "0")
+            TRANSACTIONAL_METHODS=$(grep -c "@Transactional" "$f" 2>/dev/null || echo "0")
+            if [ "$PUBLIC_METHODS" -gt 0 ] && [ "$TRANSACTIONAL_METHODS" -eq 0 ]; then
+                warn "Service class without @Transactional: $f ($PUBLIC_METHODS public methods, 0 @Transactional)"
+                MISSING_TRANSACTIONAL=$((MISSING_TRANSACTIONAL + 1))
+            fi
+        done
+        if [ "$MISSING_TRANSACTIONAL" -eq 0 ]; then
+            pass "All @Service classes have @Transactional annotations"
+        else
+            fail "$MISSING_TRANSACTIONAL @Service classes missing @Transactional"
+        fi
+    else
+        pass "No @Service classes found, skipping @Transactional check"
+    fi
+else
+    pass "No source directory found, skipping @Transactional check"
+fi
+
+# ============================================================================
+# Check 2: @PostConstruct placement
+# ============================================================================
+echo ""
+echo "--- @PostConstruct Placement ---"
+if [ -d "$SRC_DIR" ]; then
+    PC_IN_CONTROLLER=$(grep -r "@PostConstruct" "$SRC_DIR" --include="*.java" -l 2>/dev/null | xargs grep -l "@RestController\|@Controller" 2>/dev/null || true)
+    if [ -n "$PC_IN_CONTROLLER" ]; then
+        for f in $PC_IN_CONTROLLER; do
+            fail "@PostConstruct found in controller: $f (only allowed in service/config/component)"
+        done
+    else
+        pass "No @PostConstruct found in controller classes"
+    fi
+
+    # Also check @PostConstruct is in valid packages
+    PC_FILES=$(grep -r "@PostConstruct" "$SRC_DIR" --include="*.java" -l 2>/dev/null || true)
+    if [ -n "$PC_FILES" ]; then
+        for f in $PC_FILES; do
+            if echo "$f" | grep -qE "(/service/|/config/|/component/)"; then
+                : # Valid location
+            else
+                warn "@PostConstruct in unexpected package: $f (expected service/config/component)"
+            fi
+        done
+    fi
+else
+    pass "No source directory found, skipping @PostConstruct check"
+fi
+
+# ============================================================================
+# Check 3: Field injection (@Autowired on fields)
+# ============================================================================
+echo ""
+echo "--- Field Injection Detection ---"
+if [ -d "$SRC_DIR" ]; then
+    FIELD_AUTOWIRED=$(grep -rn "@Autowired" "$SRC_DIR" --include="*.java" 2>/dev/null || true)
+    CONSTRUCTOR_AUTOWIRED=$(grep -rn "@Autowired" "$SRC_DIR" --include="*.java" -B1 2>/dev/null | grep -E "\s*(public|protected|private)\s+\w+\(" || true)
+
+    if [ -n "$FIELD_AUTOWIRED" ]; then
+        # Count field-level @Autowired (not constructor)
+        FIELD_COUNT=$(echo "$FIELD_AUTOWIRED" | wc -l | tr -d ' ')
+        CONSTRUCTOR_COUNT=$(grep -rn "@Autowired\s*$" "$SRC_DIR" --include="*.java" 2>/dev/null | grep -v "//\|/\*" | wc -l | tr -d ' ')
+
+        # Heuristic: more field injections than constructor injections
+        if [ "$FIELD_COUNT" -gt "$CONSTRUCTOR_COUNT" ]; then
+            fail "Field-level @Autowired found ($FIELD_COUNT occurrences) — prefer constructor injection"
+        else
+            warn "Field-level @Autowired found ($FIELD_COUNT occurrences) — review for constructor injection migration"
+        fi
+    else
+        pass "No field-level @Autowired found (constructor injection used)"
+    fi
+else
+    pass "No source directory found, skipping field injection check"
+fi
+
+# ============================================================================
+# Check 4: Layering — web/ must not import repository/
+# ============================================================================
+echo ""
+echo "--- Layering Violations ---"
+WEB_DIRS=$(find "$SRC_DIR" -type d -name "web" -o -type d -name "controller" -o -type d -name "interfaces" 2>/dev/null)
+if [ -n "$WEB_DIRS" ]; then
+    VIOLATIONS=0
+    for webdir in $WEB_DIRS; do
+        REPO_IMPORTS=$(grep -r "import.*\.repository\.\|import.*\.infrastructure\." "$webdir" --include="*.java" 2>/dev/null || true)
+        if [ -n "$REPO_IMPORTS" ]; then
+            fail "Web layer imports repository/infrastructure directly:"
+            echo "$REPO_IMPORTS"
+            VIOLATIONS=$((VIOLATIONS + 1))
+        fi
+    done
+    if [ "$VIOLATIONS" -eq 0 ]; then
+        pass "Web layer has no direct repository imports (correct layering)"
+    fi
+else
+    pass "No web/controller directory found, skipping layering check"
+fi
+
+# ============================================================================
+# Check 5: Package naming convention
+# ============================================================================
+echo ""
+echo "--- Package Naming Convention ---"
+if [ -d "$SRC_DIR" ]; then
+    BAD_PACKAGE_FILES=0
+    for f in $(find "$SRC_DIR" -name "*.java" 2>/dev/null); do
+        # Check if package declaration follows com.{project}.{layer}.{component}
+        PACKAGE_DECL=$(grep "^package " "$f" 2>/dev/null || true)
+        if [ -n "$PACKAGE_DECL" ]; then
+            # Must start with a domain that has at least 3 parts (com.example.layer)
+            if echo "$PACKAGE_DECL" | grep -qE "^package\s+[a-z][a-z0-9]*(\.[a-z][a-z0-9]*){2,};$"; then
+                : # Good package structure: com.example.layer
+            elif echo "$PACKAGE_DECL" | grep -qE "^package\s+org\.[a-z]|[a-z]+\.example"; then
+                : # Common patterns: org.example, com.example
+            else
+                warn "Unusual package naming in $f: $PACKAGE_DECL"
+                BAD_PACKAGE_FILES=$((BAD_PACKAGE_FILES + 1))
+            fi
+        fi
+    done
+    if [ "$BAD_PACKAGE_FILES" -eq 0 ]; then
+        pass "Package naming conventions look correct"
+    fi
+else
+    pass "No source directory found, skipping package naming check"
+fi
+
+# ============================================================================
+# Summary
+# ============================================================================
+echo ""
+echo "============================================"
+echo "  Summary"
+echo "============================================"
+echo -e "  Passed:   ${GREEN}${PASS_COUNT}${NC}"
+echo -e "  Failed:   ${RED}${#ERRORS[@]}${NC}"
+echo ""
+
+if [ ${#ERRORS[@]} -gt 0 ]; then
+    echo "FAILURES:"
+    for err in "${ERRORS[@]}"; do
+        echo "  - $err"
+    done
+    exit 1
+fi
+
+echo -e "${GREEN}Spring annotation validation passed.${NC}"
+exit 0

package/templates/pi/scripts/languages/java/validate-architecture.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-architecture.sh — Java (Spring Boot Clean Architecture)
+# ============================================================================
+set -euo pipefail
+
+PASS_COUNT=0; ERRORS=(); WARNINGS=()
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
+pass() { echo -e "${GREEN}✅ PASS${NC} $1"; PASS_COUNT=$((PASS_COUNT + 1)); }
+fail() { echo -e "${RED}❌ FAIL${NC} $1"; ERRORS+=("$1"); }
+warn() { echo -e "${YELLOW}⚠️  WARN${NC} $1"; WARNINGS+=("$1"); }
+
+echo "============================================"
+echo "  Architecture Validation (Java)"
+echo "============================================"
+echo ""
+
+SRC_DIR="${1:-src/main/java}"
+
+ARCH_MODE="strict"
+if [ -f "guardian-manifest.json" ]; then
+	ARCH_MODE=$(jq -r '.archMode // "strict"' guardian-manifest.json 2>/dev/null || echo "strict")
+fi
+
+# ---------------------------------------------------------------------------
+# Layer Structure
+# ---------------------------------------------------------------------------
+echo "--- Layer Structure ---"
+if [ -d "$SRC_DIR" ]; then
+    # Check for Clean Architecture layers
+    HAS_DOMAIN=$(find "$SRC_DIR" -type d -name "domain" 2>/dev/null | head -1)
+    HAS_APPLICATION=$(find "$SRC_DIR" -type d -name "application" 2>/dev/null | head -1)
+    HAS_INFRASTRUCTURE=$(find "$SRC_DIR" -type d -name "infrastructure" 2>/dev/null | head -1)
+    HAS_WEB=$(find "$SRC_DIR" -type d -name "web" -o -type d -name "interfaces" 2>/dev/null | head -1)
+
+    LAYER_COUNT=0
+    [ -n "$HAS_DOMAIN" ] && LAYER_COUNT=$((LAYER_COUNT + 1))
+    [ -n "$HAS_APPLICATION" ] && LAYER_COUNT=$((LAYER_COUNT + 1))
+    [ -n "$HAS_INFRASTRUCTURE" ] && LAYER_COUNT=$((LAYER_COUNT + 1))
+
+    if [ "$LAYER_COUNT" -ge 3 ]; then
+        pass "Clean Architecture layers present ($LAYER_COUNT of 3)"
+    elif [ "$LAYER_COUNT" -ge 1 ]; then
+        pass "Some architecture layers present ($LAYER_COUNT of 3)"
+    else
+        warn "No Clean Architecture layers found in $SRC_DIR"
+    fi
+else
+    warn "No source directory found at $SRC_DIR"
+fi
+
+# ---------------------------------------------------------------------------
+# Package Naming Convention
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Package Naming ---"
+if [ -d "$SRC_DIR" ]; then
+    PACKAGE_DIRS=$(find "$SRC_DIR" -type d -mindepth 3 2>/dev/null | head -5)
+    if [ -n "$PACKAGE_DIRS" ]; then
+        BAD_NAMES=0
+        for dir in $(find "$SRC_DIR" -type d 2>/dev/null); do
+            BASENAME=$(basename "$dir")
+            if echo "$BASENAME" | grep -qE '^[a-z]+$'; then
+                : # valid package name
+            elif [ "$BASENAME" = "java" ] || [ "$BASENAME" = "main" ] || [ "$BASENAME" = "src" ]; then
+                : # standard directory names
+            else
+                BAD_NAMES=$((BAD_NAMES + 1))
+            fi
+        done
+        if [ "$BAD_NAMES" -eq 0 ]; then
+            pass "Package naming convention looks correct"
+        else
+            warn "Some directory names may not follow Java package conventions"
+        fi
+    else
+        pass "No deep package structure to validate"
+    fi
+else
+    warn "No source directory found"
+fi
+
+# ---------------------------------------------------------------------------
+# Canonical References
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Canonical References ---"
+if [ -d ".pi/architecture/modules" ]; then
+    MODULE_COUNT=$(find .pi/architecture/modules -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+    pass "Canonical architecture documents found ($MODULE_COUNT modules)"
+else
+    warn "No .pi/architecture/modules directory found"
+fi
+
+# ---------------------------------------------------------------------------
+# Dependency Direction
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Dependency Direction ---"
+if [ -n "$HAS_DOMAIN" ]; then
+    # Domain must NOT import infrastructure or web
+    DOMAIN_BAD_IMPORTS=0
+    for f in $(find "$HAS_DOMAIN" -name "*.java" 2>/dev/null); do
+        if grep -qE "import\s+.*\.infrastructure\." "$f" 2>/dev/null || grep -qE "import\s+.*\.web\." "$f" 2>/dev/null; then
+            if [ "$ARCH_MODE" = "strict" ]; then
+                fail "Domain layer imports from infrastructure/web: $f"
+            else
+                warn "Domain layer imports from infrastructure/web: $f (allowed in simplified mode)"
+            fi
+            DOMAIN_BAD_IMPORTS=$((DOMAIN_BAD_IMPORTS + 1))
+        fi
+    done
+    if [ "$DOMAIN_BAD_IMPORTS" -eq 0 ]; then
+        pass "Domain layer has no infrastructure or web imports"
+    fi
+else
+    pass "No domain directory, skipping dependency direction check"
+fi
+
+# ---------------------------------------------------------------------------
+# Spring Boot Specific
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Spring Boot Structure ---"
+SPRING_BOOT_APP=$(find "$SRC_DIR" -name "*Application.java" 2>/dev/null | head -1)
+if [ -n "$SPRING_BOOT_APP" ]; then
+    pass "Spring Boot main application class found: $(basename "$SPRING_BOOT_APP")"
+else
+    warn "No *Application.java Spring Boot entry point found"
+fi
+
+CONFIG_FILES=$(find . -name "application.yml" -o -name "application.yaml" -o -name "application.properties" 2>/dev/null | head -5)
+if [ -n "$CONFIG_FILES" ]; then
+    pass "Spring Boot configuration files found ($(echo "$CONFIG_FILES" | wc -l | tr -d ' ') files)"
+else
+    warn "No Spring Boot configuration files found (application.yml/properties)"
+fi
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+echo ""
+echo "============================================"
+echo "  Summary"
+echo "============================================"
+echo -e "  Passed:   ${GREEN}${PASS_COUNT}${NC}"
+echo -e "  Failed:   ${RED}${#ERRORS[@]}${NC}"
+echo ""
+
+if [ ${#ERRORS[@]} -gt 0 ]; then
+    echo "FAILURES:"
+    for err in "${ERRORS[@]}"; do
+        echo "  - $err"
+    done
+    exit 1
+fi
+
+echo -e "${GREEN}Architecture validation passed.${NC}"
+exit 0

package/templates/pi/scripts/languages/java/validate-canonical.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-canonical.sh — Java (language-agnostic, same pattern as others)
+# ============================================================================
+set -euo pipefail
+
+PASS_COUNT=0; ERRORS=(); WARNINGS=()
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
+pass() { echo -e "${GREEN}✅ PASS${NC} $1"; PASS_COUNT=$((PASS_COUNT + 1)); }
+fail() { echo -e "${RED}❌ FAIL${NC} $1"; ERRORS+=("$1"); }
+warn() { echo -e "${YELLOW}⚠️  WARN${NC} $1"; WARNINGS+=("$1"); }
+
+echo "============================================"
+echo "  Canonical Reference Validation (Java)"
+echo "============================================"
+echo ""
+
+SRC_DIR="${1:-src/main/java}"
+
+# ---------------------------------------------------------------------------
+# Architecture Module References
+# ---------------------------------------------------------------------------
+echo "--- Architecture Module References ---"
+if [ -d ".pi/architecture/modules" ]; then
+    MODULE_FILES=$(find .pi/architecture/modules -name "*.md" -not -name "module-template.md" 2>/dev/null)
+    MODULE_COUNT=$(echo "$MODULE_FILES" | wc -l | tr -d ' ')
+    if [ "$MODULE_COUNT" -gt 0 ]; then
+        pass "Architecture module docs found ($MODULE_COUNT modules)"
+    else
+        warn "No architecture module docs found"
+    fi
+else
+    warn "No .pi/architecture/modules directory found"
+fi
+
+# ---------------------------------------------------------------------------
+# Implementation File References
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- Implementation File References ---"
+if [ -d "$SRC_DIR" ]; then
+    JAVA_FILES=$(find "$SRC_DIR" -name "*.java" 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$JAVA_FILES" -gt 0 ]; then
+        # Check for canonical reference headers in Java files
+        WITH_REFS=0
+        for f in $(find "$SRC_DIR" -name "*.java" 2>/dev/null); do
+            if grep -q "Canonical Reference\|Canonical Reference:" "$f" 2>/dev/null; then
+                WITH_REFS=$((WITH_REFS + 1))
+            fi
+        done
+        if [ "$WITH_REFS" -gt 0 ]; then
+            pass "$WITH_REFS of $JAVA_FILES Java files have canonical reference headers"
+        else
+            fail "No canonical reference headers found in Java source files"
+        fi
+    else
+        pass "No Java source files found"
+    fi
+else
+    warn "No source directory found, skipping implementation reference check"
+fi
+
+# ---------------------------------------------------------------------------
+# README References
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- README / Documentation References ---"
+if [ -f "README.md" ]; then
+    if grep -qi "architecture\|canonical\|reference" README.md 2>/dev/null; then
+        pass "README.md references architecture documentation"
+    else
+        warn "README.md does not reference architecture documentation"
+    fi
+else
+    warn "No README.md found"
+fi
+
+# ---------------------------------------------------------------------------
+# ADR References
+# ---------------------------------------------------------------------------
+echo ""
+echo "--- ADR References ---"
+if [ -d ".pi/architecture/decisions" ]; then
+    ADR_COUNT=$(find .pi/architecture/decisions -name "*.md" -not -name "ADR-template.md" 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$ADR_COUNT" -gt 0 ]; then
+        pass "Architecture Decision Records found ($ADR_COUNT ADRs)"
+    else
+        warn "No ADRs found in .pi/architecture/decisions/"
+    fi
+else
+    warn "No .pi/architecture/decisions/ directory found"
+fi
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+echo ""
+echo "============================================"
+echo "  Summary"
+echo "============================================"
+echo -e "  Passed:   ${GREEN}${PASS_COUNT}${NC}"
+echo -e "  Failed:   ${RED}${#ERRORS[@]}${NC}"
+echo ""
+
+if [ ${#ERRORS[@]} -gt 0 ]; then
+    echo "FAILURES:"
+    for err in "${ERRORS[@]}"; do
+        echo "  - $err"
+    done
+    exit 1
+fi
+
+echo -e "${GREEN}Canonical reference validation passed.${NC}"
+exit 0