Improve test and build workflow with conditional execution (#381)

.github/workflows/build-guidelines.yml

@@ -1,8 +1,6 @@
-name: Build 
+name: Build
 on:
   push:
-    tags:
-      - "*.*.*"
     branches:
       - "main"
   # this fires for the temporary branch the merge queue creates
@@ -12,41 +10,118 @@ on:
       - "main"
   # workflow_call trigger to make this workflow reusable
   workflow_call:
+    inputs:
+      force_full_build:
+        type: boolean
+        default: true
 
 jobs:
+  # Determine when a full build should run
+  gatekeeper:
+    runs-on: ubuntu-latest
+    outputs:
+      run_all: ${{ steps.detect-changes.outputs.run_all }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Detect changes that should trigger a full build
+        id: detect-changes
+        shell: bash
+        run: |
+          if [[ "${{ inputs.force_full_build }}" == "true" ]]; then
+            echo "🔥  Forcing full build on workflow_call."
+            echo "run_all=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          if [[ "${{ github.ref_name }}" = "main" ]]; then
+            echo "🔥  Forcing full build on push/merge to main."
+            echo "run_all=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Determine the base commit SHA to compare changes against
+          # Supporting pull request, merge, and push
+          BASE_REF="${{
+            github.event.pull_request.base.sha ||
+            github.event.merge_group.base_sha ||
+            github.event.before
+          }}"
+
+          # Fallback for new branch, manual run, or new tag
+          if [[ -z "$BASE_REF" ]] || [[ "$BASE_REF" =~ ^0+$ ]]; then
+            echo "🔥  Forcing full build for new branch, manual run, or new tag"
+            echo "run_all=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # 🔍 Files and directories that require a full build when modified
+          WATCH_PATHS=(
+            "src/"
+            "builder/"
+            "exts/"
+            "tests/rust-examples/"
+            ".github/workflows/build-guidelines.yml"
+            ".github/workflows/check-rust-examples.yml"
+            "scripts/extract_rust_examples.py"
+            "scripts/migrate_rust_examples.py"
+            "pyproject.toml"
+            "uv.lock"
+            "make.py"
+            "spec.loc"
+          )
+
+          if git diff --quiet "$BASE_REF" HEAD -- "${WATCH_PATHS[@]}"; then
+            echo "⚠️  Skipping full build: no relevant changes detected."
+            echo "run_all=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "🔥  Forcing full build: relevant changes detected."
+            echo "run_all=true" >> "$GITHUB_OUTPUT"
+          fi
+
   # Check Rust examples compile before building docs
-  check_rust_examples:
+  check-rust-examples:
+    needs: gatekeeper
+    if: needs.gatekeeper.outputs.run_all == 'true'
     uses: ./.github/workflows/check-rust-examples.yml
 
   build:
-    needs: check_rust_examples
+    needs: [gatekeeper, check-rust-examples]
     # Always run so that 'build' (the required status check) explicitly fails
-    # when check_rust_examples fails, rather than being skipped.
+    # when check-rust-examples fails, rather than being skipped.
     # Skipped jobs don't block merge queue, but failed jobs do.
-    if: always()
+    if: |
+      always() &&
+      needs.gatekeeper.outputs.run_all == 'true'
     runs-on: ubuntu-latest
     steps:
       - name: Fail if example checks failed
-        if: needs.check_rust_examples.result != 'success'
+        if: needs.check-rust-examples.result != 'success'
         run: |
-          echo "::error::check_rust_examples workflow failed with result: ${{ needs.check_rust_examples.result }}"
-          echo "One or more Rust example checks did not pass. See the check_rust_examples job for details."
+          echo "::error::check-rust-examples workflow failed with result: ${{ needs.check-rust-examples.result }}"
+          echo "One or more Rust example checks did not pass. See the check-rust-examples job for details."
           exit 1
+
       - name: Checkout repository
         uses: actions/checkout@v4
+
       - name: Install uv
         uses: astral-sh/setup-uv@v6
+
       - name: Build documentation
         run: |
           mkdir -p build
           ./make.py 2>&1 | tee build/build.log
           # Check for a wide range of error indicators in the log
           if grep -q -E "Traceback" build/build.log; then
             echo "::error::Build errors detected in log"
-            
+
             # Extract error contexts and annotate them in the GitHub Actions UI
             echo "=== ERROR DETAILS ==="
-            
+
             # Check for the Sphinx temp error file reference and extract it if present
             TEMP_ERROR_FILE=$(grep -o '/tmp/sphinx-err-[^ ]*\.log' build/build.log | head -1)
             if [ ! -z "$TEMP_ERROR_FILE" ] && [ -f "$TEMP_ERROR_FILE" ]; then
@@ -55,7 +130,7 @@ jobs:
               echo "Saving traceback to build/sphinx_traceback.log"
               cp "$TEMP_ERROR_FILE" build/sphinx_traceback.log
             fi
-            
+
             # Check for FLS differences file reference and extract it if present
             FLS_DIFF_FILE=$(grep -o '/tmp/fls_diff_[^ ]*\.txt' build/build.log | head -1)
             if [ ! -z "$FLS_DIFF_FILE" ] && [ -f "$FLS_DIFF_FILE" ]; then
@@ -75,6 +150,7 @@ jobs:
               cp "$FLS_DIFF_FILE" build/spec_lock_file_differences.txt
             fi
           fi
+
       - name: Archive build artifacts
         uses: actions/upload-artifact@v4
         if: always()
@@ -84,7 +160,7 @@ jobs:
           retention-days: 7
           compression-level: 6  # Default compression level for a good balance of speed and size
 
-  check_typos:
+  check-typos:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository