[Feature] Path based LiveObjects Implementation

.github/workflows/liveobjects.yaml

@@ -0,0 +1,394 @@
+# Checks for the LiveObjects plugin (the AblyLiveObjects product and the
+# LiveObjects/ directory). Ported from the ably-liveobjects-swift-plugin
+# repo's Check workflow when that repo was merged into this one; the core
+# SDK's checks live in the other workflows in this directory.
+
+name: LiveObjects
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions: {}
+
+defaults:
+  run:
+    working-directory: LiveObjects
+
+jobs:
+  lint:
+    runs-on: macos-15
+
+    permissions:
+      contents: read
+
+    # From actions/cache documentation linked to below
+    env:
+      MINT_PATH: .mint/lib
+      MINT_LINK_PATH: .mint/bin
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+          submodules: true
+
+      # This step can be removed once the runners' default version of Xcode is 16.4 or above
+      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1
+        with:
+          xcode-version: 16.4
+
+      # We use caching for Mint because at the time of writing SwiftLint took about 5 minutes to build in CI, which is unacceptably slow.
+      # https://github.com/actions/cache/blob/40c3b67b2955d93d83b27ed164edd0756bc24049/examples.md#swift---mint
+      - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: LiveObjects/.mint
+          key: ${{ runner.os }}-mint-${{ hashFiles('**/Mintfile') }}
+          restore-keys: |
+            ${{ runner.os }}-mint-
+
+      - run: npm ci
+      - run: brew install mint
+      - run: mint bootstrap
+
+      - run: swift run --package-path BuildTool BuildTool lint
+
+  # Checks that every top-level declaration in the LiveObjects sources
+  # carries an @available annotation. The LiveObjects code requires newer OS
+  # versions than the rest of this package declares in its platforms, and
+  # per-declaration availability is how it declares this (see
+  # Scripts/annotate-liveobjects-availability.py).
+  check-availability-annotations:
+    runs-on: macos-15
+
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+          submodules: true
+
+      # This step can be removed once the runners' default version of Xcode is 16.4 or above
+      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1
+        with:
+          xcode-version: 16.4
+
+      # The compiler check: public declarations must carry availability.
+      # (-require-explicit-availability must be spelled as a frontend flag;
+      # the driver flag of the same name is a no-op.)
+      - name: Check availability of public declarations (compiler)
+        working-directory: .
+        run: swift build --target AblyLiveObjects -Xswiftc -Xfrontend -Xswiftc -require-explicit-availability=error
+
+      # The script check: all top-level declarations (including internal
+      # ones) must carry availability. The annotation script is idempotent,
+      # so a non-empty diff means somebody added a declaration without an
+      # annotation.
+      - name: Check availability of all top-level declarations (script)
+        working-directory: .
+        run: |
+          python3 Scripts/annotate-liveobjects-availability.py
+          git diff --exit-code LiveObjects/Sources
+
+  generate-matrices:
+    runs-on: macos-15
+
+    permissions:
+      contents: read
+
+    outputs:
+      matrix: ${{ steps.generation-step.outputs.matrix }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+          submodules: true
+
+      # This step can be removed once the runners' default version of Xcode is 16.4 or above
+      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1
+        with:
+          xcode-version: 16.4
+
+      - id: generation-step
+        run: swift run --package-path BuildTool BuildTool generate-matrices >> $GITHUB_OUTPUT
+
+  build-and-test-spm:
+    name: SPM (Xcode ${{ matrix.tooling.xcodeVersion }})
+    runs-on: macos-15
+    needs: generate-matrices
+
+    permissions:
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.generate-matrices.outputs.matrix).withoutPlatform }}
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+          submodules: true
+      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1
+        with:
+          xcode-version: ${{ matrix.tooling.xcodeVersion }}
+
+      # https://forums.swift.org/t/warnings-as-errors-for-libraries-frameworks/58393/2
+      #
+      # These run at the repo root: the package that contains the
+      # AblyLiveObjects targets is the root ably-cocoa package. The test run
+      # is filtered to the LiveObjects test module; the rest of the package's
+      # tests are run by the core SDK's own workflows (though `swift test`
+      # builds all of the package's test targets, so -warnings-as-errors
+      # covers their compilation here too — note that the warning set is a
+      # property of this job's Xcode version, and newer toolchains may warn
+      # about things this one does not).
+      - name: Build (warnings as errors)
+        working-directory: .
+        run: swift build -Xswiftc -warnings-as-errors
+      - name: Run LiveObjects tests
+        working-directory: .
+        run: swift test -Xswiftc -warnings-as-errors --filter 'AblyLiveObjectsTests\.'
+
+  build-release-configuration-spm:
+    name: SPM, `release` configuration (Xcode ${{ matrix.tooling.xcodeVersion }})
+    runs-on: macos-15
+    needs: generate-matrices
+
+    permissions:
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.generate-matrices.outputs.matrix).withoutPlatform }}
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+          submodules: true
+      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1
+        with:
+          xcode-version: ${{ matrix.tooling.xcodeVersion }}
+
+      # https://forums.swift.org/t/warnings-as-errors-for-libraries-frameworks/58393/2
+      - name: Build (release, warnings as errors)
+        working-directory: .
+        run: swift build -Xswiftc -warnings-as-errors --configuration release
+
+  build-and-test-xcode:
+    name: Xcode, ${{matrix.platform}} (Xcode ${{ matrix.tooling.xcodeVersion }})
+    runs-on: macos-15
+    needs: generate-matrices
+
+    permissions:
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.generate-matrices.outputs.matrix).withPlatform }}
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+          submodules: true
+      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1
+        with:
+          xcode-version: ${{ matrix.tooling.xcodeVersion }}
+
+      # We run these as two separate steps so that we can easily see the execution time of each step.
+
+      - name: Build for testing
+        env:
+          PLATFORM: ${{ matrix.platform }}
+        run: swift run --package-path BuildTool BuildTool build-library-for-testing --platform "$PLATFORM"
+
+      - name: Run tests
+        env:
+          PLATFORM: ${{ matrix.platform }}
+        run: swift run --package-path BuildTool BuildTool test-library --platform "$PLATFORM" --without-building
+
+  code-coverage:
+    name: Generate code coverage
+    runs-on: macos-15
+
+    permissions:
+      contents: read
+      checks: write
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+          submodules: true
+
+      # This step can be removed once the runners' default version of Xcode is 16.4 or above
+      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1
+        with:
+          xcode-version: 16.4
+
+      - run: swift run --package-path BuildTool BuildTool generate-code-coverage --result-bundle-path CodeCoverage.xcresult
+
+      # Generate a Markdown report of the code coverage information and add it to the workflow run.
+      #
+      # This tool is the best option that I could find after a brief look at the options. There are a few things that I wish it could do:
+      #
+      # - post a message on the pull request, like they do on Kotlin
+      # - offer more fine-grained configuration about which data to include in the report (I only care about code coverage, not test results, and I don't care about code coverage of the AblyLiveObjectsTests target)
+      #
+      # but it'll do for now (we can always fork or have another look for tooling later).
+      - uses: slidoapp/xcresulttool@9c51e32ae0320e0ca9b63240e4da8e974ac573e3 # v3.1.0
+        with:
+          path: LiveObjects/CodeCoverage.xcresult
+          # This title will be used for the sidebar item that this job adds to GitHub results page for this workflow
+          title: LiveObjects code coverage results
+          # Turning off as much non-code-coverage information as it lets me
+          show-passed-tests: false
+        if: success() || failure()
+
+  build-release-configuration-xcode:
+    name: Xcode, `release` configuration, ${{matrix.platform}} (Xcode ${{ matrix.tooling.xcodeVersion }})
+    runs-on: macos-15
+    needs: generate-matrices
+
+    permissions:
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.generate-matrices.outputs.matrix).withPlatform }}
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+          submodules: true
+      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1
+        with:
+          xcode-version: ${{ matrix.tooling.xcodeVersion }}
+
+      - name: Build library
+        env:
+          PLATFORM: ${{ matrix.platform }}
+        run: swift run --package-path BuildTool BuildTool build-library --platform "$PLATFORM" --configuration release
+
+  check-example-app:
+    name: Example app, ${{matrix.platform}} (Xcode ${{ matrix.tooling.xcodeVersion }})
+    runs-on: macos-15
+    needs: generate-matrices
+
+    permissions:
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.generate-matrices.outputs.matrix).withPlatform }}
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+          submodules: true
+      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1
+        with:
+          xcode-version: ${{ matrix.tooling.xcodeVersion }}
+
+      - name: Build example app
+        env:
+          PLATFORM: ${{ matrix.platform }}
+        run: swift run --package-path BuildTool BuildTool build-example-app --platform "$PLATFORM"
+
+  check-documentation:
+    runs-on: macos-15
+
+    permissions:
+      deployments: write
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+          submodules: true
+
+      # This step can be removed once the runners' default version of Xcode is 16.4 or above
+      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1
+        with:
+          xcode-version: 16.4
+
+      # Dry run upload-action to get base-path url
+      - name: Dry-Run Upload (to get url)
+        id: preupload
+        uses: ably/sdk-upload-action@4e694297f208b72b5a9f6b1248a1556f19f821d6 # v2
+        with:
+          mode: preempt
+          sourcePath: LiveObjects/AblyLiveObjects.doccarchive
+          githubToken: ${{ secrets.GITHUB_TOKEN }}
+          artifactName: AblyLiveObjects
+
+      # Build the documentation using xcodebuild's built-in DocC support and
+      # transform it for static hosting. (The standalone plugin repo used the
+      # swift-docc-plugin package plugin instead; we deliberately avoid that
+      # here because it would have to be a dependency of the root manifest,
+      # where ably-cocoa's consumers would resolve it.)
+      - name: Build documentation
+        env:
+          HOSTING_BASE_PATH: ${{ steps.preupload.outputs.base-path }}
+        run: |
+          xcodebuild docbuild -scheme AblyLiveObjects -destination generic/platform=macOS -derivedDataPath DerivedData
+          $(xcrun --find docc) process-archive transform-for-static-hosting \
+            "$(find DerivedData -name AblyLiveObjects.doccarchive -print -quit)" \
+            --output-path AblyLiveObjects.doccarchive \
+            --hosting-base-path "$HOSTING_BASE_PATH"
+
+      # Configure AWS credentials for uploading documentation
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4
+        with:
+          aws-region: eu-west-2
+          role-to-assume: arn:aws:iam::${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}:role/ably-sdk-builds-ably-cocoa
+          role-session-name: "${{ github.run_id }}-${{ github.run_number }}"
+
+      # Upload the generated documentation
+      - name: Upload Documentation
+        uses: ably/sdk-upload-action@4e694297f208b72b5a9f6b1248a1556f19f821d6 # v2
+        with:
+          sourcePath: LiveObjects/AblyLiveObjects.doccarchive
+          githubToken: ${{ secrets.GITHUB_TOKEN }}
+          artifactName: AblyLiveObjects
+          landingPagePath: documentation/ablyliveobjects
+
+  # We use this job as a marker that all of the required checks have completed.
+  # This allows us to configure a single required status check in our branch
+  # protection rules instead of having to type loads of different check names
+  # into the branch protection web UI (and keep this list up to date as we
+  # tweak the matrices).
+  all-checks-completed:
+    runs-on: ubuntu-latest
+
+    permissions: {}
+
+    needs:
+      - lint
+      - check-availability-annotations
+      - build-and-test-spm
+      - build-release-configuration-spm
+      - build-and-test-xcode
+      - build-release-configuration-xcode
+      - check-example-app
+      - check-documentation
+      - code-coverage
+
+    steps:
+      - name: No-op
+        # Override the workflow-wide default working directory: this job runs
+        # without a checkout, so the LiveObjects directory does not exist.
+        working-directory: .
+        run: "true"