From 4f274fa2104cf80062a0833f8adca3cbfe89621a Mon Sep 17 00:00:00 2001
From: Stuart Montgomery <smontgomery@apple.com>
Date: Fri, 19 Dec 2025 14:30:39 -0600
Subject: [PATCH] Introduce a macOS DocC soundness check

---
 .github/workflows/scripts/check-docs.sh |  7 +++-
 .github/workflows/soundness.yml         | 56 +++++++++++++++++++++++++
 2 files changed, 61 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/scripts/check-docs.sh b/.github/workflows/scripts/check-docs.sh
index f170af15..fec40a17 100755
--- a/.github/workflows/scripts/check-docs.sh
+++ b/.github/workflows/scripts/check-docs.sh
@@ -3,7 +3,7 @@
 ##
 ## This source file is part of the Swift.org open source project
 ##
-## Copyright (c) 2024 Apple Inc. and the Swift project authors
+## Copyright (c) 2025 Apple Inc. and the Swift project authors
 ## Licensed under Apache License v2.0 with Runtime Library Exception
 ##
 ## See https://swift.org/LICENSE.txt for license information
@@ -23,7 +23,10 @@ if [ ! -f .spi.yml ]; then
 fi
 
 if ! command -v yq &> /dev/null; then
-  apt -q update && apt -yq install yq
+  case "$(uname -s)" in
+  Darwin*) echo brew install yq;;
+  Linux*) echo apt -q update && apt -yq install yq;;
+  esac
 fi
 
 package_files=$(find . -maxdepth 1 -name 'Package*.swift')
diff --git a/.github/workflows/soundness.yml b/.github/workflows/soundness.yml
index ce8f63f0..73d7e432 100644
--- a/.github/workflows/soundness.yml
+++ b/.github/workflows/soundness.yml
@@ -31,6 +31,26 @@ on:
         type: string
         description: "Additional arguments that should be passed to docc"
         default: ""
+      docs_check_macos_enabled:
+        type: boolean
+        description: "Boolean to enable the macOS docs check job. Defaults to false."
+        default: false
+      docs_check_macos_version:
+        type: string
+        description: "macOS version for the macOS docs check job."
+        default: "sequoia"
+      docs_check_macos_arch:
+        type: string
+        description: "macOS arch for the macOS docs check job."
+        default: "ARM64"
+      docs_check_macos_xcode_version:
+        type: string
+        description: "Xcode version for the macOS docs check job."
+        default: "26.0"
+      docs_check_macos_additional_arguments:
+        type: string
+        description: "Additional arguments that should be passed to docc for the macOS docs check job."
+        default: ""
       unacceptable_language_check_enabled:
         type: boolean
         description: "Boolean to enable the acceptable language check job. Defaults to true."
@@ -164,6 +184,42 @@ jobs:
           ADDITIONAL_DOCC_ARGUMENTS: ${{ inputs.docs_check_additional_arguments }}
         run: ${{ steps.script_path.outputs.root }}/.github/workflows/scripts/check-docs.sh
 
+  docs-check-macos:
+    name: Documentation check (macOS)
+    if: ${{ inputs.docs_check_macos_enabled }}
+    runs-on: [self-hosted, macos, "${{ inputs.docs_check_macos_version }}", "${{ inputs.docs_check_macos_arch }}"]
+    timeout-minutes: 20
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          submodules: true
+      - name: Checkout swiftlang/github-workflows repository
+        if: ${{ github.repository != 'swiftlang/github-workflows' }}
+        uses: actions/checkout@v4
+        with:
+          repository: swiftlang/github-workflows
+          path: github-workflows
+      - name: Determine script-root path
+        id: script_path
+        run: |
+          if [ "${{ github.repository }}" = "swiftlang/github-workflows" ]; then
+            echo "root=$GITHUB_WORKSPACE" >> $GITHUB_OUTPUT
+          else
+            echo "root=$GITHUB_WORKSPACE/github-workflows" >> $GITHUB_OUTPUT
+          fi
+      - name: Select Xcode
+        run: echo "DEVELOPER_DIR=/Applications/Xcode_${{ inputs.docs_check_macos_xcode_version }}.app" >> $GITHUB_ENV
+      - name: Swift version
+        run: xcrun swift --version
+      - name: Clang version
+        run: xcrun clang --version
+      - name: Run documentation check
+        env:
+          ADDITIONAL_DOCC_ARGUMENTS: ${{ inputs.docs_check_macos_additional_arguments }}
+        run: ${{ steps.script_path.outputs.root }}/.github/workflows/scripts/check-docs.sh
+
   unacceptable-language-check:
     name: Unacceptable language check
     if: ${{ inputs.unacceptable_language_check_enabled }}