codeql.yml

# CodeQL security + quality scanning (GitHub "advanced setup" as a committed workflow).
#
# We use a workflow rather than the API "default setup" on purpose: the default-setup PUT needs a PAT with
# security_events scope, while the workflow's built-in GITHUB_TOKEN already has `security-events: write` — no
# extra credentials. Findings land in the repo's Security → Code scanning tab (and enable Copilot Autofix).
#
# Doc/screenshot-only PRs skip the whole analysis via the shared detect-doc-only reusable workflow. Unlike
# ci.yml/lint.yml — whose required checks are job names, where a skipped job counts as a pass — the required
# "CodeQL" check is posted by the code-scanning service after SARIF upload, NOT by this job. So skipping the
# job would leave a *required* "CodeQL" check stuck on "Expected — Waiting for status". For that reason
# "CodeQL" has been REMOVED from main's required status checks; it still runs on every push to main and on
# the weekly schedule, so the default branch stays fully scanned. (Re-add it as required only if this gate
# is reverted.)
#
# C# is analysed in MANUAL build mode: it compiles BlocksBeyondTheStars.CI.slnf (every .NET project except the
# Windows-only Launcher) so CodeQL gets full type/call resolution. Manual mode extracts only what the compiler
# compiles, so the Unity client C# under client/Assets/ — which needs the Unity editor and isn't in any .csproj
# we build — drops out of the C# scan. That trade is deliberate: the security-relevant code (GameServer,
# Networking, Persistence, Api, Client.Core) is fully analysed, while the dropped Unity scripts are
# MonoBehaviour rendering/UI with little security surface. The wiki/minigames untrusted-input parsing now
# lives in native C# (Client.Core), which IS analysed by the csharp scan. The earlier buildless (build-mode: none) C# scan
# left ~23% of calls unresolved (below CodeQL's 85% threshold → "low analysis quality"), risking false
# positives / missed results. Python and Actions stay buildless (build-mode: none).

name: CodeQL

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    # Weekly catch-all so new CodeQL queries run against the default branch even without a push.
    - cron: '27 4 * * 1'

permissions:
  contents: read

jobs:
  # Shared doc/image detection (see .github/workflows/detect-doc-only.yml). Always runs so pushes/schedule
  # succeed; `nondocs` gates analyze so a doc- or image-only PR skips scanning entirely.
  changes:
    uses: ./.github/workflows/detect-doc-only.yml

  analyze:
    name: CodeQL (${{ matrix.language }})
    needs: changes
    # Run on every push to main and on the weekly schedule; for a PR, only when a non-doc/non-image file
    # changed. Doc/screenshot-only PRs skip — safe because "CodeQL" is no longer a required check (see header).
    if: github.event_name != 'pull_request' || needs.changes.outputs.nondocs == 'true'
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read
      actions: read
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: csharp
            build-mode: manual
          - language: python
            build-mode: none
          - language: actions
            build-mode: none
    steps:
      # The C# scan is the expensive one — it runs a full `dotnet build` of CI.slnf, while python/actions
      # are buildless and take seconds. Measured 2026-07-19..27: CodeQL was the #2 wall-clock consumer of
      # the whole repo (230 min over 60 runs) and nearly all of it was csharp on pull requests. Since the
      # "CodeQL" check is deliberately NOT required on main (see the header), restricting csharp to pushes
      # to main and the weekly schedule cannot block a PR — and main is still scanned on every merge, which
      # is exactly the coverage the header promises. python/actions keep running on PRs (#530).
      - name: Skip the C# scan on pull requests
        id: gate
        shell: bash
        run: |
          if [ "${{ matrix.language }}" = "csharp" ] && [ "${{ github.event_name }}" = "pull_request" ]; then
            echo "skip=true" >> "$GITHUB_OUTPUT"
            echo "C# CodeQL runs on pushes to main + the weekly schedule, not on PRs (#530)."
          else
            echo "skip=false" >> "$GITHUB_OUTPUT"
          fi

      - uses: actions/checkout@v5
        if: steps.gate.outputs.skip != 'true'

      # C# only: the manual build below needs the .NET SDK. Skipped for the buildless languages.
      - name: Set up .NET
        if: steps.gate.outputs.skip != 'true' && matrix.language == 'csharp'
        uses: actions/setup-dotnet@v5
        with:
          dotnet-version: '10.0.x'

      - name: Initialize CodeQL
        if: steps.gate.outputs.skip != 'true'
        uses: github/codeql-action/init@v4
        with:
          languages: ${{ matrix.language }}
          build-mode: ${{ matrix.build-mode }}
          queries: security-extended

      # Manual C# build so CodeQL traces the compiler and resolves all types/calls. CI.slnf is the same
      # solution filter ci.yml uses (every project except the Windows-only WinForms launcher), so it builds
      # on the Linux runner. No -warnaserror here: this gate is for security analysis, not style enforcement
      # (ci.yml already enforces 0 warnings). Skipped for the buildless languages.
      - name: Build C# (solution filter)
        if: steps.gate.outputs.skip != 'true' && matrix.language == 'csharp'
        run: dotnet build BlocksBeyondTheStars.CI.slnf -c Release

      - name: Analyze
        if: steps.gate.outputs.skip != 'true'
        uses: github/codeql-action/analyze@v4
        with:
          category: "/language:${{ matrix.language }}"