codeql.yml

# For most projects, this workflow file will not need changing; you simply need
# to commit it to your repository.
#
# You may wish to alter this file to override the set of languages analyzed,
# or to provide custom queries or build logic.
#
# ******** NOTE ********
# We have attempted to detect the languages in your repository. Please check
# the `language` matrix defined below to confirm you have the correct set of
# supported CodeQL languages.
#
name: "CodeQL Advanced"

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
  schedule:
    - cron: '36 2 * * 6'

# Supersede a PR's own older analyses; never supersede one on main.
#
# This is the stock starter workflow and had no concurrency control at all. The matrix runs FOUR
# language analyses, so every push to a PR enqueued four more and nothing cancelled the previous
# four. On 2026-08-06 one branch was rebased three times and left twelve stale analyses running;
# repo-wide, CodeQL was 15 of 28 queued jobs -- the single largest consumer of a saturated queue,
# analysing commits nobody would merge.
#
# Grouped by head branch for pull_request, and by `github.run_id` for push, so every commit on main
# gets its OWN group and can never be cancelled by a later one. Grouping main pushes together would
# make them queue and cancel each other, which silently stops analysing intermediate commits -- the
# exact trap `ci.yml` documents, and the one `pages.yml` was failing on the same day.
#
# NOTE what this deliberately does NOT do: it does not add a `paths:` filter and does not drop the
# pull_request trigger. Both would cut the queue further and both reduce SECURITY COVERAGE, which is
# a decision for a human, not a throughput fix. Superseding a run that a newer commit has already
# replaced loses nothing -- skipping analysis of a path does.
concurrency:
  group: codeql-${{ github.event_name == 'pull_request' && github.head_ref || github.run_id }}
  cancel-in-progress: true

# Default-deny for any job added later. Both existing jobs (`scope`, `analyze`) already scope their
# own permissions, so this changes nothing today — Aikido's MED-2 named two other workflows and was
# wrong about this one. It is here because a job added WITHOUT its own block inherits the
# repository default, and the repository default is not `contents: read`. A safe default costs one
# line; noticing that a new job lacked a block would cost a review that may not happen.
permissions:
  contents: read

jobs:
  # Decide WHICH language analyses this event needs, and emit them as the matrix below.
  #
  # Why: the matrix ran all four languages on every pull-request push regardless of content. A
  # roadmap sweep touching only `docs/*.md` still queued an actions, a javascript-typescript, a
  # python AND a rust analysis. Measured 2026-08-06 during a merge jam, CodeQL was 15 of 28 queued
  # jobs and most were analysing languages the diff never touched.
  #
  # THIS REDUCES SECURITY COVERAGE IF IT IS WRONG, so every branch fails TOWARD analysing more:
  #   * push to main and the weekly schedule  -> ALL languages, always. Never scoped.
  #   * the changed-file list is unavailable  -> ALL languages.
  #   * a path matches nothing known          -> ignored, but if NOTHING matches, the analyse job
  #                                              is skipped entirely (a docs-only PR has no code to
  #                                              analyse; main will still analyse it on merge).
  # A path may map to several languages; matching is deliberately generous.
  scope:
    name: Scope languages to the diff
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
    outputs:
      matrix: ${{ steps.pick.outputs.matrix }}
    steps:
    - id: pick
      env:
        GH_TOKEN: ${{ github.token }}
        REPO: ${{ github.repository }}
        EVENT: ${{ github.event_name }}
        PR: ${{ github.event.pull_request.number }}
      run: |
        set -uo pipefail
        ALL='[{"language":"actions","build-mode":"none"},{"language":"javascript-typescript","build-mode":"none"},{"language":"python","build-mode":"none"},{"language":"rust","build-mode":"none"}]'
        emit () { echo "matrix=$1" >> "$GITHUB_OUTPUT"; echo "scope: $2"; exit 0; }

        # Full coverage on main and on the schedule. Only pull requests are ever scoped.
        [ "$EVENT" = "pull_request" ] || emit "$ALL" "$EVENT is not a pull request -> all languages"

        files=$(gh pr view "$PR" --repo "$REPO" --json files --jq '.files[].path' 2>/dev/null) || files=""
        [ -n "$files" ] || emit "$ALL" "changed-file list unavailable -> all languages (fail-safe)"
        echo "changed files:"; echo "$files" | sed 's/^/  /'

        langs=""
        add () { case ",$langs," in *",$1,"*) ;; *) langs="${langs:+$langs,}$1" ;; esac; }
        while IFS= read -r f; do
          case "$f" in .github/workflows/*|.github/actions/*) add actions ;; esac
          case "$f" in *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs|*package.json|*package-lock.json) add javascript-typescript ;; esac
          case "$f" in *.py|*requirements*.txt|*pyproject.toml) add python ;; esac
          case "$f" in *.rs|*Cargo.toml|*Cargo.lock) add rust ;; esac
        done <<< "$files"

        [ -n "$langs" ] || emit "[]" "no analysable source changed -> skipping (main re-analyses on merge)"
        m=$(printf '%s' "$langs" | jq -R -c 'split(",") | map({language: ., "build-mode": "none"})')
        [ -n "$m" ] || emit "$ALL" "matrix build failed -> all languages (fail-safe)"
        emit "$m" "scoped to: $langs"

  analyze:
    name: Analyze (${{ matrix.language }})
    needs: scope
    if: needs.scope.outputs.matrix != '[]'
    # Runner size impacts CodeQL analysis time. To learn more, please see:
    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
    #   - https://gh.io/supported-runners-and-hardware-resources
    #   - https://gh.io/using-larger-runners (GitHub.com only)
    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
    permissions:
      # required for all workflows
      security-events: write

      # required to fetch internal or private CodeQL packs
      packages: read

      # only required for workflows in private repositories
      actions: read
      contents: read

    strategy:
      fail-fast: false
      matrix:
        include: ${{ fromJSON(needs.scope.outputs.matrix) }}
        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
        # Use `c-cpp` to analyze code written in C, C++ or both
        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
    steps:
    - name: Checkout repository
      uses: actions/checkout@v7

    # Add any setup steps before running the `github/codeql-action/init` action.
    # This includes steps like installing compilers or runtimes (`actions/setup-node`
    # or others). This is typically only required for manual builds.
    # - name: Setup runtime (example)
    #   uses: actions/setup-example@v1

    # Initializes the CodeQL tools for scanning.
    - name: Initialize CodeQL
      uses: github/codeql-action/init@v4
      with:
        languages: ${{ matrix.language }}
        build-mode: ${{ matrix.build-mode }}
        # If you wish to specify custom queries, you can do so here or in a config file.
        # By default, queries listed here will override any specified in a config file.
        # Prefix the list here with "+" to use these queries and those in the config file.

        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
        # queries: security-extended,security-and-quality

    # (all languages use build-mode: none — if one ever needs "manual", add its build step here)
    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v4
      with:
        category: "/language:${{matrix.language}}"