loader-integration.yml

on:
  pull_request:
    branches: [master]

env:
  http_proxy: http://proxy-dmz.intel.com:912
  https_proxy: http://proxy-dmz.intel.com:912
  DOCKER_BUILDKIT: '1'

jobs:
  build:
    runs-on: [self-hosted, Linux]
    if: github.repository_owner == 'intel-innersource'
    steps:
    - name: Print runner machine metrics
      # Captures build machine capabilities at job start so we have context
      # for diagnosing slow runs and tuning parallelism (e.g. make -j flags).
      run: | #bash
        echo "=== Host ==="
        hostname
        echo ""
        echo "=== CPU ==="
        lscpu | grep -E "Model name|Socket|Core|Thread|CPU\(s\)"
        echo ""
        echo "=== Memory ==="
        free -h
        echo ""
        echo "=== Disk ==="
        df -h --output=target,size,used,avail,pcent | grep -E "^Filesystem|^/$|^/home|^/tmp"
    - name: Checkout spec-head
      uses: actions/checkout@v4
      with:
        clean: true
        fetch-depth: 0
        fetch-tags: true
        path: spec-head
    - name: Checkout spec-base
      uses: actions/checkout@v4
      with:
        ref: master
        clean: true
        fetch-depth: 0
        fetch-tags: true
        path: spec-base
    - name: Get spec-base SHA
      id: spec-base-sha
      run: echo "sha=$(git -C spec-base rev-parse HEAD)" >> $GITHUB_OUTPUT
    - name: Restore spec-base artifacts cache
      id: cache-spec-base
      uses: actions/cache/restore@v4
      with:
        path: |
          spec-base/docs
          spec-base/include
        key: spec-base-artifacts-${{ steps.spec-base-sha.outputs.sha }}
    - name: Build container image
      run: | #bash
        docker build \
          --build-arg http_proxy=http://proxy-dmz.intel.com:912 \
          --build-arg https_proxy=http://proxy-dmz.intel.com:912 \
          -t ghcr.io/oneapi-src/spec-build:latest \
          -f spec-head/.github/docker/build.Dockerfile \
          spec-head/
    - name: Detect version from git tags
      run: | #bash
        # Find the most recent tag matching v<MAJOR>.<MINOR>* (single 'v' prefix only)
        LATEST_TAG=$(git -C spec-head tag --sort=-version:refname | grep -E '^v[0-9]+\.[0-9]+' | head -1)
        if [ -z "$LATEST_TAG" ]; then
          echo "Error: No version tags matching v<MAJOR>.<MINOR>.* found" >&2
          exit 1
        fi
        # Extract MAJOR.MINOR only
        VER=$(echo "$LATEST_TAG" | grep -oP '^v\K[0-9]+\.[0-9]+')
        echo "Detected version: $VER (from tag $LATEST_TAG)"
        echo "VER=$VER" >> $GITHUB_ENV
    - name: Generate spec-head artifacts
      run: | #bash
        docker run \
          --rm \
          -v $PWD:$PWD \
          -w $PWD/spec-head/scripts \
          -e TZ=UTC \
          ghcr.io/oneapi-src/spec-build:latest \
          /opt/spec-venv/bin/python3 ./run.py --debug '--html' '--rst' '--!build' --ver $VER
    - name: Generate spec-base artifacts
      if: steps.cache-spec-base.outputs.cache-hit != 'true'
      run: | #bash
        docker run \
          --rm \
          -v $PWD:$PWD \
          -w $PWD/spec-base/scripts \
          -e TZ=UTC \
          ghcr.io/oneapi-src/spec-build:latest \
          /opt/spec-venv/bin/python3 ./run.py --debug '--html' '--rst' '--!build' --ver $VER
    - name: Determine if there is a diff between header files
      id: include-diff
      run: | #bash
        if git diff --quiet --exit-code -- spec-head/include spec-base/include; then
            echo "diff=0" >> $GITHUB_OUTPUT
        else
            echo "diff=1" >> $GITHUB_OUTPUT
        fi
    - name: Get header diff
      if: steps.include-diff.outputs.diff == '1'
      run: git diff --no-index spec-base/include spec-head/include > header-diff.patch || true
    - name: Write comment with formatting to DIFF_COMMENT
      if: steps.include-diff.outputs.diff == '1'
      shell: python3 {0}
      run: |
        import os
        with open('header-diff.patch', 'r') as f:
            diff_content = f.read()
        diff_comment = f"```diff\n{diff_content}\n```"
        with open('results_comment.txt', 'w') as results_file:
            results_file.write(diff_comment)
    - uses: actions/upload-artifact@v4
      if: steps.include-diff.outputs.diff == '1'
      id: upload-diff-artifact
      with:
        name: Level Zero Header Diff
        path: results_comment.txt
    - name: Output artifact URL
      if: steps.include-diff.outputs.diff == '1'
      run:  echo 'Artifact URL is ${{ steps.upload-diff-artifact.outputs.artifact-url }}'
    - name: Write comment to PR
      if: steps.include-diff.outputs.diff == '1'
      uses: actions/github-script@v7
      with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            [, pullRequestId] = /refs\/pull\/(\d+)\/merge/g.exec(context.ref);
            github.rest.issues.createComment({
              issue_number: pullRequestId,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: "The Level Zero header diff can be found [here](${{ steps.upload-diff-artifact.outputs.artifact-url }})."
            });
    - name: Determine if there is a diff between RST files
      id: rst-diff
      run: | #bash
        if git diff --quiet --exit-code -- spec-head/docs/source spec-base/docs/source; then
            echo "diff=0" >> $GITHUB_OUTPUT
        else
            echo "diff=1" >> $GITHUB_OUTPUT
        fi
    - name: Get RST diff
      if: steps.rst-diff.outputs.diff == '1'
      run: git diff --no-index spec-base/docs/source spec-head/docs/source > rst-diff.patch || true
    - name: Write comment with formatting to RST_DIFF_COMMENT
      if: steps.rst-diff.outputs.diff == '1'
      shell: python3 {0}
      run: |
        import os
        with open('rst-diff.patch', 'r') as f:
            diff_content = f.read()
        diff_comment = f"```diff\n{diff_content}\n```"
        with open('rst_results_comment.txt', 'w') as results_file:
            results_file.write(diff_comment)
    - uses: actions/upload-artifact@v4
      if: steps.rst-diff.outputs.diff == '1'
      id: upload-rst-diff-artifact
      with:
        name: Level Zero RST Diff
        path: rst_results_comment.txt
    - name: Output RST artifact URL
      if: steps.rst-diff.outputs.diff == '1'
      run:  echo 'RST Artifact URL is ${{ steps.upload-rst-diff-artifact.outputs.artifact-url }}'
    - name: Write RST diff comment to PR
      if: steps.rst-diff.outputs.diff == '1'
      uses: actions/github-script@v7
      with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            [, pullRequestId] = /refs\/pull\/(\d+)\/merge/g.exec(context.ref);
            github.rest.issues.createComment({
              issue_number: pullRequestId,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: "The Level Zero RST diff can be found [here](${{ steps.upload-rst-diff-artifact.outputs.artifact-url }})."
            });
    - name: Determine if there is a diff between HTML files
      id: html-diff
      run: | #bash
        if git diff --quiet --exit-code -- spec-head/docs/html spec-base/docs/html; then
            echo "diff=0" >> $GITHUB_OUTPUT
        else
            echo "diff=1" >> $GITHUB_OUTPUT
        fi
    - name: Get HTML diff
      if: steps.html-diff.outputs.diff == '1'
      run: git diff --no-index spec-base/docs/html spec-head/docs/html > html-diff.patch || true
    - name: Write comment with formatting to HTML_DIFF_COMMENT
      if: steps.html-diff.outputs.diff == '1'
      shell: python3 {0}
      run: |
        import os
        with open('html-diff.patch', 'r') as f:
            diff_content = f.read()
        diff_comment = f"```diff\n{diff_content}\n```"
        with open('html_results_comment.txt', 'w') as results_file:
            results_file.write(diff_comment)
    - uses: actions/upload-artifact@v4
      if: steps.html-diff.outputs.diff == '1'
      id: upload-html-diff-artifact
      with:
        name: Level Zero HTML Diff
        path: html_results_comment.txt
    - name: Output HTML artifact URL
      if: steps.html-diff.outputs.diff == '1'
      run:  echo 'HTML Artifact URL is ${{ steps.upload-html-diff-artifact.outputs.artifact-url }}'
    - name: Write HTML diff comment to PR
      if: steps.html-diff.outputs.diff == '1'
      uses: actions/github-script@v7
      with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            [, pullRequestId] = /refs\/pull\/(\d+)\/merge/g.exec(context.ref);
            github.rest.issues.createComment({
              issue_number: pullRequestId,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: "The Level Zero HTML diff can be found [here](${{ steps.upload-html-diff-artifact.outputs.artifact-url }})."
            });
    - name: Upload HTML documentation artifacts for preview
      if: steps.html-diff.outputs.diff == '1'
      uses: actions/upload-artifact@v4
      id: upload-html-docs
      with:
        name: html-documentation-preview
        path: |
          spec-head/docs/html/
          spec-base/docs/html/
        retention-days: 30
    - name: Comment with HTML preview info
      if: steps.html-diff.outputs.diff == '1'
      uses: actions/github-script@v7
      with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const prNumber = context.payload.pull_request.number;
            const branchName = context.payload.pull_request.head.ref;
            const repoOwner = context.repo.owner;
            const repoName = context.repo.repo;
            
            // Check if custom domain is configured (set in workflow env or repo settings)
            const customDomain = process.env.PAGES_CUSTOM_DOMAIN || '';
            const baseUrl = customDomain 
              ? `https://${customDomain}` 
              : `https://${repoOwner}.github.io/${repoName}`;
            
            let body = "## 📚 HTML Documentation Preview\n\n";
            body += "The HTML documentation artifacts have been uploaded. ";
            body += "You can download and view them locally, or wait for the automatic GitHub Pages deployment.\n\n";
            body += `**Artifact**: [Download HTML Documentation](${{ steps.upload-html-docs.outputs.artifact-url }})\n\n`;
            body += "### 🔗 GitHub Pages Links (after deployment):\n\n";
            body += `- **This PR #${prNumber} (branch: \`${branchName}\`)**: ${baseUrl}/pr-${prNumber}/\n`;
            body += `- **Master branch (base)**: ${baseUrl}/master/\n`;
            body += `- **All versions**: ${baseUrl}/\n\n`;
            body += "*Note: GitHub Pages links will be available after the deploy-docs workflow completes.*";
            
            github.rest.issues.createComment({
              issue_number: prNumber,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: body
            });
    - name: Checkout loader-head
      uses: actions/checkout@v4
      with:
        clean: true
        repository: oneapi-src/level-zero
        ref: master
        path: loader-head
        token: ${{ secrets.LOADER_INNERSOURCE_TOKEN }}
    - name: Get loader master HEAD SHA
      # Fetch the current HEAD SHA of the loader master branch. This SHA is used
      # as the cache key for base.dump — so we only rebuild the base when master
      # has actually changed, not on every PR run.
      id: loader-master-sha
      uses: actions/github-script@v7
      with:
        github-token: ${{ secrets.LOADER_INNERSOURCE_TOKEN }}
        script: |
          const { data } = await github.rest.repos.getBranch({
            owner: 'oneapi-src',
            repo: 'level-zero',
            branch: 'master'
          });
          core.setOutput('sha', data.commit.sha);
    - name: Restore base ABI dump cache
      # Attempt to restore a previously generated ABI dump (base.dump) for the
      # loader master branch, keyed on the master HEAD SHA. On a cache hit the
      # expensive loader build and abi-dumper steps below are all skipped,
      # saving several minutes per run.
      # The restore-keys fallback matches any older base-abi-dump entry so the
      # very first run after a new master commit still gets a warm start from
      # the previous ABI dump.
      # Cache entries are evicted by GitHub after 7 days of non-use, so storage
      # stays bounded to a handful of small ABI dump entries at any given time.
      # Note: save-always is deprecated — saving is handled by the explicit
      # actions/cache/save step at the end of the job using if: always().
      id: cache-base-abi-dump
      uses: actions/cache/restore@v4
      with:
        path: base.dump
        key: base-abi-dump-${{ steps.loader-master-sha.outputs.sha }}
        restore-keys: |
          base-abi-dump-
    - name: Checkout loader-base
      uses: actions/checkout@v4
      with:
        clean: true
        repository: oneapi-src/level-zero
        ref: master
        path: loader-base
        token: ${{ secrets.LOADER_INNERSOURCE_TOKEN }}
    - uses: intel-sandbox/action-setup-jq@main
    - name: json2src head
      run: | #bash
        docker run \
          --rm \
          --interactive \
          -v $PWD:$PWD \
          -w $PWD/loader-head \
          ghcr.io/oneapi-src/spec-build:latest \
          python3 ./scripts/json2src.py --ver $VER . < spec-head/scripts/input.json
    - name: Copy head include files
      working-directory: spec-head
      run: | #bash
        set -o pipefail
        jq -r '.[] | select(.|test("^../include"))' scripts/generated.json |
        cut -c 4- |
        sort |
        xargs -I{} cp -v ./{} ../loader-head/{}
    - name: Determine if there is a diff between loader source files
      id: loader-source-diff
      run: | #bash
        if git diff --quiet --exit-code -- loader-head/source loader-base/source; then
            echo "diff=0" >> $GITHUB_OUTPUT
        else
            echo "diff=1" >> $GITHUB_OUTPUT
        fi
    - name: Get loader diff
      if: steps.loader-source-diff.outputs.diff == '1'
      run: git diff --no-index loader-base/source loader-head/source > loader-diff.patch || true
    - name: Write comment with formatting to LOADER_DIFF_COMMENT
      if: steps.loader-source-diff.outputs.diff == '1'
      shell: python3 {0}
      run: |
        import os
        with open('loader-diff.patch', 'r') as f:
            loader_diff_content = f.read()
        loader_diff_comment = f"```diff\n{loader_diff_content}\n```"
        with open('loader_results_comment.txt', 'w') as results_file:
            results_file.write(loader_diff_comment)
    - uses: actions/upload-artifact@v4
      if: steps.loader-source-diff.outputs.diff == '1'
      id: upload-loader-diff-artifact
      with:
        name: Level Zero Loader Diff
        path: loader_results_comment.txt
    - name: Output loader diff artifact URL
      if: steps.loader-source-diff.outputs.diff == '1'
      run:  echo 'Artifact URL is ${{ steps.upload-loader-diff-artifact.outputs.artifact-url }}'
    - name: Write loader diff comment to PR
      if: steps.loader-source-diff.outputs.diff == '1'
      uses: actions/github-script@v7
      with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            [, pullRequestId] = /refs\/pull\/(\d+)\/merge/g.exec(context.ref);
            github.rest.issues.createComment({
              issue_number: pullRequestId,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: "The Level Zero Loader diff can be found [here](${{ steps.upload-loader-diff-artifact.outputs.artifact-url }})."
            });
    - name: Build loader-head
      working-directory: loader-head
      run: | #bash
        docker run \
          --rm \
          --interactive \
          -v $PWD:$PWD \
          -w $PWD \
          -e CXXFLAGS="-Og -g -fno-lto" \
          ghcr.io/oneapi-src/spec-build:latest \
          bash -e <<EOF
        mkdir -p build
        cd build
        cmake -D CMAKE_BUILD_TYPE=Debug ..
        make -j$(nproc)
        EOF
    - name: Build loader-base
      # Skipped on cache hit — base ABI dump was restored from cache, so there
      # is no need to rebuild the loader from source. Must use Debug + -Og -g
      # -fno-lto so that DWARF debug info is present and complete for abi-dumper.
      if: steps.cache-base-abi-dump.outputs.cache-hit != 'true'
      working-directory: loader-base
      run: | #bash
        docker run \
          --rm \
          --interactive \
          -v $PWD:$PWD \
          -w $PWD \
          -e CXXFLAGS="-Og -g -fno-lto" \
          ghcr.io/oneapi-src/spec-build:latest \
          bash -e <<EOF
        mkdir -p build
        cd build
        cmake -D CMAKE_BUILD_TYPE=Debug ..
        make -j$(nproc)
        EOF
    - name: Checkout abi-dumper
      uses: actions/checkout@v4
      with:
        clean: true
        repository: lvc/abi-dumper
        path: abi-dumper
    - name: Setup abi-dumper
      run: | #bash
        cp abi-dumper/abi-dumper.pl .
        chmod +x abi-dumper.pl
    - name: Dump loader-base
      # Skipped on cache hit — base ABI dump was restored from cache.
      # -lambda ensures lambda functions are included in the ABI snapshot.
      # Run as root and chown output — same reasoning as Dump loader-head.
      # The resulting base.dump is automatically saved to the ABI dump cache
      # by actions/cache when this job completes successfully.
      if: steps.cache-base-abi-dump.outputs.cache-hit != 'true'
      run: | #bash
        docker run \
          --rm \
          -v $PWD:$PWD \
          -w $PWD \
          ghcr.io/oneapi-src/spec-build:latest \
          ./abi-dumper.pl \
            loader-base/build/lib/libze_loader.so \
            -lver $(cat loader-base/build/VERSION) \
            -public-headers loader-base/include \
            -lambda \
            -o base.dump
        docker run --rm -v $PWD:$PWD -w $PWD \
          ghcr.io/oneapi-src/spec-build:latest \
          chown $(id -u):$(id -g) base.dump
    - name: Dump loader-head
      # Run as root (Docker default) so POSIX ACL mask entries on the
      # self-hosted runner filesystem cannot block the write. Ownership of the
      # output file is immediately restored to the runner user so
      # actions/cache can read and save it.
      run: | #bash
        docker run \
          --rm \
          -v $PWD:$PWD \
          -w $PWD \
          ghcr.io/oneapi-src/spec-build:latest \
          ./abi-dumper.pl \
            loader-head/build/lib/libze_loader.so \
            -lver $(cat loader-head/build/VERSION)-1 \
            -public-headers loader-head/include \
            -lambda \
            -o head.dump
        docker run --rm -v $PWD:$PWD -w $PWD \
          ghcr.io/oneapi-src/spec-build:latest \
          chown $(id -u):$(id -g) head.dump

    - name: Restore abi-compliance-checker cache
      id: cache-acc
      uses: actions/cache/restore@v4
      with:
        path: abi-compliance-checker
        key: abi-compliance-checker-2.3
    - name: Download and setup abi-compliance-checker
      if: steps.cache-acc.outputs.cache-hit != 'true'
      run: |
        wget https://github.com/lvc/abi-compliance-checker/tarball/2.3 -O abi-compliance-checker.tar.gz
        mkdir -p abi-compliance-checker
        tar -xzf abi-compliance-checker.tar.gz --strip-components=1 -C abi-compliance-checker
        chmod +x abi-compliance-checker/abi-compliance-checker.pl
    - name: Fix API_CURRENT_VERSION check
      id: fix_current_version
      continue-on-error: true
      run: |
        docker run \
          --rm \
          -v $PWD:$PWD \
          -w $PWD \
          ghcr.io/oneapi-src/spec-build:latest \
          python3 spec-head/scripts/update_ze_api_version.py base.dump head.dump
    - name: Compare dumps
      id: abi-check
      continue-on-error: true
      run: |
        docker run \
          --rm \
          -v $PWD:$PWD \
          -w $PWD \
          ghcr.io/oneapi-src/spec-build:latest \
          abi-compliance-checker/abi-compliance-checker.pl \
            -l libze_loader \
            -old base.dump \
            -new head.dump \
            -report-path report.html
    - name: Check for reviewer approval of ABI failure
      id: check-approval
      if: steps.abi-check.outcome == 'failure'
      uses: actions/github-script@v7
      with:
        github-token: ${{ secrets.GITHUB_TOKEN }}
        script: |
          const { data: reviews } = await github.rest.pulls.listReviews({
            owner: context.repo.owner,
            repo: context.repo.repo,
            pull_number: context.issue.number,
          });
          
          const approvedReviews = reviews.filter(review => 
            review.state === 'APPROVED' && 
            review.body && 
            review.body.toLowerCase().includes('abi-failure-approved')
          );
          
          if (approvedReviews.length > 0) {
            console.log('ABI failure has been approved by reviewer');
            core.setOutput('approved', 'true');
          } else {
            console.log('No reviewer approval found for ABI failure');
            core.setOutput('approved', 'false');
          }
    - uses: actions/upload-artifact@v4
      id: abi-report-artifact
      continue-on-error: true
      with:
        name: abi-report
        path: report.html
    - name: Write loader ABI Report comment to PR
      continue-on-error: true
      if: "steps.loader-source-diff.outputs.diff == '1' || steps.include-diff.outputs.diff == '1' || steps.rst-diff.outputs.diff == '1' || steps.html-diff.outputs.diff == '1'"
      uses: actions/github-script@v7
      with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            [, pullRequestId] = /refs\/pull\/(\d+)\/merge/g.exec(context.ref);
            const abiStatus = "${{ steps.abi-check.outcome }}";
            let body = "The Level Zero ABI Report can be found [here](${{ steps.abi-report-artifact.outputs.artifact-url }}).";
            
            if (abiStatus === 'failure') {
              body += "\n\n⚠️ **ABI Compliance Check Failed**\n\n";
              body += "If this ABI change is intentional and acceptable, a reviewer can approve it by:\n";
              body += "1. Reviewing the ABI report above\n";
              body += "2. Leaving an **approval review** with the keyword `abi-failure-approved` in the comment\n\n";
              body += "This will allow the workflow to pass despite the ABI compliance failure.";
            }
            
            github.rest.issues.createComment({
              issue_number: pullRequestId,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: body
            });
    - name: Save spec-base artifacts cache
      if: always() && steps.cache-spec-base.outputs.cache-hit != 'true'
      uses: actions/cache/save@v4
      with:
        path: |
          spec-base/docs
          spec-base/include
        key: ${{ steps.cache-spec-base.outputs.cache-primary-key }}
    - name: Save abi-compliance-checker cache
      if: always() && steps.cache-acc.outputs.cache-hit != 'true'
      uses: actions/cache/save@v4
      with:
        path: abi-compliance-checker
        key: ${{ steps.cache-acc.outputs.cache-primary-key }}
    - name: Save base ABI dump cache
      # Always runs (even on job failure) so base.dump is persisted regardless
      # of ABI check outcome. base.dump reflects loader master state, not PR
      # outcome — skipped only when the restore step already had a cache hit
      # to avoid overwriting an identical entry.
      if: always() && steps.cache-base-abi-dump.outputs.cache-hit != 'true'
      uses: actions/cache/save@v4
      with:
        path: base.dump
        key: ${{ steps.cache-base-abi-dump.outputs.cache-primary-key }}
    - name: Fail if ABI check failed and not approved
      if: steps.abi-check.outcome == 'failure' && steps.check-approval.outputs.approved != 'true'
      run: |
        echo "ABI compliance check failed and no reviewer approval found."
        echo "To approve this failure, a reviewer must leave an approval review containing 'abi-failure-approved' in the comment."
        exit 1