soundness.yml

name: Soundness

on:
  workflow_call:
    inputs:
      api_breakage_check_enabled:
        type: boolean
        description: "Boolean to enable the API breakage check job. Defaults to true."
        default: true
      api_breakage_check_allowlist_path:
        type: string
        description: "Path to a file that will be passed as --breakage-allowlist-path to swift package diagnose-api-breaking-changes"
        default: ""
      api_breakage_pre_build_command:
        type: string
        description: "Execute before running the AOU breakage check"
        default: ""
      api_breakage_check_baseline:
        type: string
        description: "The tag against which API breakages that should be used as the baseline for the API breakage check. By default the PR base is used."
        default: ""
      api_breakage_check_container_image:
        type: string
        description: "Container image for the API breakage check job. Defaults to latest Swift Ubuntu image."
        default: "swift:6.4-noble"
      api_breakage_check_additional_arguments:
        type: string
        description: "Additional arguments to pass directory to the `swift package diagnose-api-breaking-changes` invocation."
        default: ""
      docs_check_enabled:
        type: boolean
        description: "Boolean to enable the docs check job. Defaults to true."
        default: true
      docs_check_container_image:
        type: string
        description: "Container image for the docs check job. Defaults to latest Swift Ubuntu image."
        default: "swift:6.4-noble"
      docs_check_additional_arguments:
        type: string
        description: "Additional arguments that should be passed to docc"
        default: ""
      docs_check_targets:
        type: string
        description: "List of targets to check for documentation."
        default: ""
      docs_check_analyze:
        type: boolean
        description: "Boolean to pass --analyze to the docs check. Defaults to true."
        default: true
      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: "tahoe"
      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: ""
      docs_check_macos_targets:
        type: string
        description: "List of targets to check for documentation."
        default: ""
      docs_check_macos_analyze:
        type: boolean
        description: "Boolean to pass --analyze to the macOS docs check. Defaults to true."
        default: true
      unacceptable_language_check_enabled:
        type: boolean
        description: "Boolean to enable the acceptable language check job. Defaults to true."
        default: true
      unacceptable_language_check_word_list:
        type: string
        description: "List of unacceptable words. Defaults to a sensible list of words."
        default: "blacklist whitelist slave master sane sanity insane insanity kill killed killing hang hung hanged hanging"  # ignore-unacceptable-language
      license_header_check_enabled:
        type: boolean
        description: "Boolean to enable the license header check job. Defaults to true."
        default: true
      license_header_check_project_name:
        type: string
        description: "Name of the project called out in the license header. Required unless `license_header_check_enabled` is false or a `.license_header_template` file is present."
        default: ""
      broken_symlink_check_enabled:
        type: boolean
        description: "Boolean to enable the broken symlink check job. Defaults to true."
        default: true
      format_check_enabled:
        type: boolean
        description: "Boolean to enable the format check job. Defaults to true."
        default: true
      format_check_container_image:
        type: string
        description: "Container image for the format check job. Defaults to latest Swift Ubuntu image."
        default: "swift:6.4-noble"
      shell_check_enabled:
        type: boolean
        description: "Boolean to enable the shell check job. Defaults to true."
        default: true
      shell_check_container_image:
        type: string
        description: "Container image for the shell check job. Defaults to latest Ubuntu 24.04 Noble image."
        default: "ubuntu:noble"
      yamllint_check_enabled:
        type: boolean
        description: "Boolean to enable the YAML lint check job. Defaults to true."
        default: true
      python_lint_check_enabled:
        type: boolean
        description: "Boolean to enable the Python lint check job. Defaults to true."
        default: true
      linux_pre_build_command:
        type: string
        description: "Linux command to execute before building the Swift package"
        default: ""
      concurrency_group_suffix:
        type: string
        description: "Optional suffix appended to the concurrency group. Use this when calling soundness.yml from a matrix so that matrix entries don't cancel each other."
        default: ""

permissions:
  contents: read

## We are cancelling previously triggered workflow runs
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}-soundness-${{ inputs.concurrency_group_suffix }}
  cancel-in-progress: true

jobs:
  api-breakage-check:
    name: API breakage check
    if: ${{ inputs.api_breakage_check_enabled }}
    runs-on: ubuntu-latest
    container:
      image: ${{ inputs.api_breakage_check_container_image }}
    timeout-minutes: 40
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          # This is set to true since swift package diagnose-api-breaking-changes is
          # cloning the repo again and without it being set to true this job won't work for
          # private repos.
          persist-credentials: true
          submodules: true
          fetch-tags: true
          fetch-depth: 0  # Fetching tags requires fetch-depth: 0 (https://github.com/actions/checkout/issues/1471)
      - name: Mark the workspace as safe
        # https://github.com/actions/checkout/issues/766
        run: git config --global --add safe.directory ${GITHUB_WORKSPACE}
      - name: Pre-build
        # zizmor: ignore[template-injection]
        run: ${{ inputs.api_breakage_pre_build_command }}
      - name: Run API breakage check
        shell: bash
        env:
          API_BREAKAGE_CHECK_BASELINE: ${{ inputs.api_breakage_check_baseline }}
          API_BREAKAGE_CHECK_ALLOWLIST_PATH: ${{ inputs.api_breakage_check_allowlist_path }}
          API_BREAKAGE_CHECK_ADDITIONAL_ARGUMENTS: ${{ inputs.api_breakage_check_additional_arguments }}
        # zizmor: ignore[template-injection]
        run: |
          ${{ inputs.linux_pre_build_command }}
          if [[ -z "${API_BREAKAGE_CHECK_BASELINE}" ]]; then
            git fetch ${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY} ${GITHUB_BASE_REF}:pull-base-ref
            BASELINE_REF='pull-base-ref'
          else
            BASELINE_REF="${API_BREAKAGE_CHECK_BASELINE}"
          fi
          echo "Using baseline: $BASELINE_REF"
          if [[ -z "${API_BREAKAGE_CHECK_ALLOWLIST_PATH}" ]]; then
            swift package diagnose-api-breaking-changes "$BASELINE_REF" ${API_BREAKAGE_CHECK_ADDITIONAL_ARGUMENTS}
          else
            swift package diagnose-api-breaking-changes "$BASELINE_REF" --breakage-allowlist-path "${API_BREAKAGE_CHECK_ALLOWLIST_PATH}" ${API_BREAKAGE_CHECK_ADDITIONAL_ARGUMENTS}
          fi

  docs-check:
    name: Documentation check
    if: ${{ inputs.docs_check_enabled }}
    runs-on: ubuntu-latest
    container:
      image: ${{ inputs.docs_check_container_image }}
    timeout-minutes: 20
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          persist-credentials: false
          submodules: true
      - name: Locate the workflows scripts
        id: workflows_scripts
        uses: $/.github/actions/workflows-scripts
      - name: Run documentation check
        env:
          ADDITIONAL_DOCC_ARGUMENTS: ${{ inputs.docs_check_additional_arguments }}
          DOCC_ANALYZE: ${{ inputs.docs_check_analyze }}
          DOCS_TARGETS: ${{ inputs.docs_check_targets}}
          SCRIPTS_DIRECTORY: ${{ steps.workflows_scripts.outputs.scripts_directory }}
        run: |
          set -x
          ${{ inputs.linux_pre_build_command }}
          analyze_arg=""
          doc_target_arg=""
          if [ "${DOCS_TARGETS}" != "" ] ; then
            doc_target_arg="--doc-targets ${DOCS_TARGETS}"
          fi
          if [ "${DOCC_ANALYZE}" != "true" ]; then
            analyze_arg="--no-analyze"
          fi
          "${SCRIPTS_DIRECTORY}/check-docs.sh" ${analyze_arg} ${doc_target_arg} --additional-docc-arguments ${ADDITIONAL_DOCC_ARGUMENTS}

  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@v7
        with:
          persist-credentials: false
          submodules: true
      - name: Locate the workflows scripts
        id: workflows_scripts
        uses: $/.github/actions/workflows-scripts
      - name: Select Xcode
        env:
          XCODE_VERSION: ${{ inputs.docs_check_macos_xcode_version }}
        run: echo "DEVELOPER_DIR=/Applications/Xcode_${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 }}
          DOCC_ANALYZE: ${{ inputs.docs_check_macos_analyze }}
          DOCS_TARGETS: ${{ inputs.docs_check_macos_targets}}
          SCRIPTS_DIRECTORY: ${{ steps.workflows_scripts.outputs.scripts_directory }}
        run: |
          analyze_arg=""
          doc_target_arg=""
          if [ "${DOCS_TARGETS}" != "" ] ; then
            doc_target_arg="--doc-targets ${DOCS_TARGETS}"
          fi
          if [ "${DOCC_ANALYZE}" != "true" ]; then
            analyze_arg="--no-analyze"
          fi
          set -x
          "${SCRIPTS_DIRECTORY}/check-docs.sh" ${analyze_arg} ${doc_target_arg} --additional-docc-arguments ${ADDITIONAL_DOCC_ARGUMENTS}

  unacceptable-language-check:
    name: Unacceptable language check
    if: ${{ inputs.unacceptable_language_check_enabled }}
    runs-on: ubuntu-latest
    timeout-minutes: 1
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          persist-credentials: false
          submodules: true
      - name: Locate the workflows scripts
        id: workflows_scripts
        uses: $/.github/actions/workflows-scripts
      - name: Run unacceptable language check
        env:
          UNACCEPTABLE_WORD_LIST: ${{ inputs.unacceptable_language_check_word_list}}
          SCRIPTS_DIRECTORY: ${{ steps.workflows_scripts.outputs.scripts_directory }}
        run: ${SCRIPTS_DIRECTORY}/check-unacceptable-language.sh

  license-header-check:
    name: License headers check
    if: ${{ inputs.license_header_check_enabled }}
    runs-on: ubuntu-latest
    timeout-minutes: 1
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          persist-credentials: false
          submodules: true
      - name: Locate the workflows scripts
        id: workflows_scripts
        uses: $/.github/actions/workflows-scripts
      - name: Run license header check
        env:
          PROJECT_NAME: ${{ inputs.license_header_check_project_name }}
          SCRIPTS_DIRECTORY: ${{ steps.workflows_scripts.outputs.scripts_directory }}
        run: ${SCRIPTS_DIRECTORY}/check-license-header.sh

  broken-symlink-check:
    name: Broken symlinks check
    if: ${{ inputs.broken_symlink_check_enabled }}
    runs-on: ubuntu-latest
    timeout-minutes: 1
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          persist-credentials: false
          submodules: true
      - name: Locate the workflows scripts
        id: workflows_scripts
        uses: $/.github/actions/workflows-scripts
      - name: Run broken symlinks check
        env:
          SCRIPTS_DIRECTORY: ${{ steps.workflows_scripts.outputs.scripts_directory }}
        run: ${SCRIPTS_DIRECTORY}/check-broken-symlinks.sh

  format-check:
    name: Format check
    if: ${{ inputs.format_check_enabled }}
    runs-on: ubuntu-latest
    container:
      image: ${{ inputs.format_check_container_image }}
    timeout-minutes: 20
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          persist-credentials: false
          submodules: true
      - name: Locate the workflows scripts
        id: workflows_scripts
        uses: $/.github/actions/workflows-scripts
      - name: Mark the workspace as safe
        # https://github.com/actions/checkout/issues/766
        run: git config --global --add safe.directory ${GITHUB_WORKSPACE}
      - name: Run format check
        env:
          SCRIPTS_DIRECTORY: ${{ steps.workflows_scripts.outputs.scripts_directory }}
        run: ${SCRIPTS_DIRECTORY}/check-swift-format.sh

  shell-check:
    name: Shell check
    if: ${{ inputs.shell_check_enabled }}
    runs-on: ubuntu-latest
    container:
      image: ${{ inputs.shell_check_container_image }}
    timeout-minutes: 5
    steps:
      - name: Install git
        run: which git || (apt -q update && apt -yq install git)
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          persist-credentials: false
          submodules: true
      - name: Mark the workspace as safe
        # https://github.com/actions/checkout/issues/766
        run: git config --global --add safe.directory ${GITHUB_WORKSPACE}
      - name: Run shellcheck
        run: |
          which shellcheck || (apt -q update && apt -yq install shellcheck)
          git ls-files -z '*.sh' | xargs -0 --no-run-if-empty shellcheck

  yaml-lint-check:
    name: YAML lint check
    if: ${{ inputs.yamllint_check_enabled }}
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          persist-credentials: false
          submodules: true
      - name: Locate the workflows scripts
        id: workflows_scripts
        uses: $/.github/actions/workflows-scripts
      - name: Run yamllint
        env:
          CONFIGS_DIRECTORY: ${{ steps.workflows_scripts.outputs.configs_directory }}
        run: |
          which yamllint || (apt -q update && apt install -yq yamllint)
          cd ${GITHUB_WORKSPACE}
          if [ ! -f ".yamllint.yml" ]; then
            echo "Downloading default yamllint config file"
            cat "${CONFIGS_DIRECTORY}/yamllint.yml" > .yamllint.yml
          fi
          yamllint --strict --config-file .yamllint.yml .

  python-lint-check:
    name: Python lint check
    if: ${{ inputs.python_lint_check_enabled }}
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          persist-credentials: false
          submodules: true
      - name: Locate the workflows scripts
        id: workflows_scripts
        uses: $/.github/actions/workflows-scripts
      - name: Run flake8
        env:
          CONFIGS_DIRECTORY: ${{ steps.workflows_scripts.outputs.configs_directory }}
        run: |
          pip3 install flake8 flake8-import-order
          cd ${GITHUB_WORKSPACE}
          if [ ! -f ".flake8" ]; then
            echo "Downloading default flake8 config file"
            cat "${CONFIGS_DIRECTORY}/.flake8" > .flake8
          fi
          flake8