pr-check-changelog.sh

#!/bin/bash

# ==============================================================================
# Executes When:
#   - Run by GitHub Actions workflow: .github/workflows/pr-check-changelog.yml
#   - Triggers: workflow_dispatch (manual) and pull_request (opened, edited, synch).
#
# Goal:
#   It acts as a gatekeeper for Pull Requests, blocking any merge unless the user
#   has added a new entry to CHANGELOG.md and correctly placed it under the
#   [Unreleased] section with a proper category subtitle.
#
# ------------------------------------------------------------------------------
# Flow: Basic Idea
#   1. Grabs the official blueprints (upstream/main) to compare against current work.
#   2. Checks if anything new was written. If not, fails immediately.
#   3. Walks through the file line-by-line to ensure new notes are strictly filed
#      under [Unreleased] and organized under a category (e.g., "Added", "Fixed").
#   4. If notes are missing, misplaced, or dangling, it fails the build.
#      If filed correctly, it approves the build.
#
# ------------------------------------------------------------------------------
# Flow: Detailed Technical Steps
#
# 1️⃣ Network Setup & Fetch
#    - Action: Sets up a remote connection to GitHub and runs 'git fetch upstream main'.
#    - Why: Needs the "Source of Truth" to compare the Pull Request against.
#
# 2️⃣ Diff Analysis & Visualization
#    - Action: Runs 'git diff upstream/main -- CHANGELOG.md'.
#    - UX/Display: Prints raw diff with colors (Green=Additions, Red=Deletions)
#      strictly for human readability in logs; logic does not rely on colors.
#    - Logic: Extracts two lists:
#      * added_bullets: Every line starting with '+' (new text).
#      * deleted_bullets: Every line starting with '-' (removed text).
#    - Immediate Fail Check: If 'added_bullets' is empty, sets failed=1 and exits.
#      (You cannot merge code without a changelog entry).
#
# 3️⃣ Context Tracking
#    As the script reads the file line-by-line, it tracks:
#    - current_release: Main version header (e.g., [Unreleased] or [1.0.0]).
#    - current_subtitle: Sub-category (e.g., ### Added, ### Fixed).
#    - in_unreleased: Flag (0 or 1).
#       * 1 (True)  -> Currently inside [Unreleased] (Safe Zone).
#       * 0 (False) -> Reading an old version (Danger Zone).
#
# 4️⃣ Sorting
#    The script matches new lines against the current context:
#    Flag is ON (1) AND Subtitle is Set 	    -> correctly_placed    		-> PASS ✅
#    Flag is ON (1) BUT Subtitle is Empty     -> orphan_entries       		-> FAIL ❌ (It's dangling, not under a category)
#    Flag is OFF (0)          				    -> wrong_release_entries	-> FAIL ❌ (edited old history)
#
# 5️⃣ Final Result
#    Aggregates failures from Step 4. If any FAIL buckets are not empty, exit 1.
#
# ------------------------------------------------------------------------------
# Parameters:
#   None. (The script accepts no command-line arguments).
#
# Environment Variables (Required):
#   - GITHUB_REPOSITORY: Used to fetch the upstream 'main' branch for comparison.
#
# Dependencies:
#   - git (must be able to fetch upstream)
#   - grep, sed (standard Linux utilities)
#   - CHANGELOG.md (file must exist in the root directory)
#
# Permissions:
#   - 'contents: read' (to access the file structure).
#   - Network access (to run 'git fetch upstream').
#
# Returns:
#   0 (Success) - Changes are valid and correctly placed.
#   1 (Failure) - Missing entries, wrong placement (e.g. under released version),
#                 orphan entries (no subtitle), or accidental deletions.
# ==============================================================================

CHANGELOG="CHANGELOG.md"

# ANSI color codes
RED="\033[31m"
GREEN="\033[32m"
YELLOW="\033[33m"
RESET="\033[0m"

failed=0

# Fetch upstream
git remote add upstream https://github.com/${GITHUB_REPOSITORY}.git
git fetch upstream main >/dev/null 2>&1

# Get raw diff
raw_diff=$(git diff upstream/main -- "$CHANGELOG")

# 1️⃣ Show raw diff with colors
echo "=== Raw git diff of $CHANGELOG against upstream/main ==="
while IFS= read -r line; do
    if [[ $line =~ ^\+ && ! $line =~ ^\+\+\+ ]]; then
        echo -e "${GREEN}$line${RESET}"
    elif [[ $line =~ ^- && ! $line =~ ^--- ]]; then
        echo -e "${RED}$line${RESET}"
    else
        echo "$line"
    fi
done <<< "$raw_diff"
echo "================================="

# 2️⃣ Extract added bullet lines
added_bullets=()
while IFS= read -r line; do
    [[ -n "$line" ]] && added_bullets+=("$line")
done < <(echo "$raw_diff" | sed -n 's/^+//p' | grep -E '^[[:space:]]*[-*]' | sed '/^[[:space:]]*$/d')

# 2️⃣a Extract deleted bullet lines
deleted_bullets=()
while IFS= read -r line; do
    [[ -n "$line" ]] && deleted_bullets+=("$line")
done < <(echo "$raw_diff" | grep '^\-' | grep -vE '^(--- |\+\+\+ |@@ )' | sed 's/^-//')

# 2️⃣b Warn if no added entries
if [[ ${#added_bullets[@]} -eq 0 ]]; then
    echo -e "${RED}❌ No new changelog entries detected in this PR.${RESET}"
    echo -e "${YELLOW}⚠️ Please add an entry in [UNRELEASED] under the appropriate subheading.${RESET}"
    failed=1
fi

# 3️⃣ Initialize results
correctly_placed=""
orphan_entries=""
wrong_release_entries=""

# 4️⃣ Walk through changelog to classify entries
current_release=""
current_subtitle=""
in_unreleased=0

while IFS= read -r line; do
    # Track release sections
    if [[ $line =~ ^##\ \[Unreleased\] ]]; then
        current_release="Unreleased"
        in_unreleased=1
        current_subtitle=""
        continue
    elif [[ $line =~ ^##\ \[.*\] ]]; then
        current_release="$line"
        in_unreleased=0
        current_subtitle=""
        continue
    elif [[ $line =~ ^### ]]; then
        current_subtitle="$line"
        continue
    fi

    # Check each added bullet
    for added in "${added_bullets[@]}"; do
        if [[ "$line" == "$added" ]]; then
            if [[ "$in_unreleased" -eq 1 && -n "$current_subtitle" ]]; then
                correctly_placed+="$added   (placed under $current_subtitle)"$'\n'
            elif [[ "$in_unreleased" -eq 1 && -z "$current_subtitle" ]]; then
                orphan_entries+="$added   (NOT under a subtitle)"$'\n'
            elif [[ "$in_unreleased" -eq 0 ]]; then
                wrong_release_entries+="$added   (added under released version $current_release)"$'\n'
            fi
        fi
    done
done < "$CHANGELOG"

# 5️⃣ Display results
if [[ -n "$orphan_entries" ]]; then
    echo -e "${RED}❌ Some CHANGELOG entries are not under a subtitle in [Unreleased]:${RESET}"
    echo "$orphan_entries"
    failed=1
fi

if [[ -n "$wrong_release_entries" ]]; then
    echo -e "${RED}❌ Some changelog entries were added under a released version (should be in [Unreleased]):${RESET}"
    echo "$wrong_release_entries"
    failed=1
fi

if [[ -n "$correctly_placed" ]]; then
    echo -e "${GREEN}✅ Some CHANGELOG entries are correctly placed under [Unreleased]:${RESET}"
    echo "$correctly_placed"
fi

# 6️⃣ Display deleted entries
if [[ ${#deleted_bullets[@]} -gt 0 ]]; then
    echo -e "${RED}❌ Changelog entries removed in this PR:${RESET}"
    for deleted in "${deleted_bullets[@]}"; do
        echo -e "  - ${RED}$deleted${RESET}"
    done
    echo -e "${YELLOW}⚠️ Please add these entries back under the appropriate sections${RESET}"
fi

# 7️⃣ Exit with failure if any bad entries exist
if [[ $failed -eq 1 ]]; then
    echo -e "${RED}❌ Changelog check failed.${RESET}"
    exit 1
else
    echo -e "${GREEN}✅ Changelog check passed.${RESET}"
    exit 0
fi