codeql.yml

name: CodeQL

# Deep semantic SAST (taint / data-flow analysis) that complements bandit and the curated semgrep
# rules in security.yml — it finds vulnerable flows those pattern matchers can't, e.g. untrusted
# HL7/config data reaching a sink across function boundaries.
#
# WHY THIS IS GUARDED TO THE REPO SLUG: CodeQL uploads results to GitHub code scanning, which on a
# PRIVATE repo requires paid GitHub Advanced Security (see security.yml's header note). THIS repo is
# PUBLIC, so CodeQL + code scanning are FREE here. The analyze job is gated on the slug so it stays a
# skipped no-op anywhere the upload would fail or be billed — a fork, or the retired private archive.
#
# (Pre-cutover this described MEFORORG as "the OSS mirror" of a private source repo, and said the job
# ran "once publish.ps1 mirrors this file". Both premises are gone: MEFORORG is the source, and the
# publish machinery was deleted. The GUARD was already right — only its rationale had rotted.)
#
# PINNING CAVEAT: this repo SHA-pins every Action for supply-chain integrity. actions/checkout below
# reuses the repo's existing v7.0.0 pin; the github/codeql-action steps are on the v3 tag for now
# because the live commit SHA must be looked up at authoring — SHA-pin them before treating this as a
# hardened gate (OSSF Scorecard / zizmor would flag the unpinned tags).
#
# ALTERNATIVE (no file): you can instead enable CodeQL "default setup" from
# Settings -> Security -> Code scanning (one toggle, auto-pinned, auto-updated). Default setup and this
# advanced workflow are mutually exclusive — if you turn default setup ON, delete this file.
on:
  # BACKLOG #340. THE QUEUE IS LIVE AND THESE THREE CONTEXTS ARE REQUIRED, so without this
  # trigger CodeQL never reports on a merge_group event and NOTHING MERGES. Measured
  # 2026-08-27 on the first entry the queue ever held: PR 619 sat AWAITING_CHECKS with 32
  # check-runs green on gh-readonly-queue/main/pr-619-bca93ee1 and exactly three contexts
  # absent -- CodeQL, CodeQL (python), CodeQL (javascript-typescript).
  #
  # security.yml's own on: block predicted this in the PR that added merge_group to the other
  # four workflows: "the failure mode of the reverse order is total -- enable a queue while a
  # required context's workflow has no merge_group trigger and that check never reports in the
  # queue, so NOTHING MERGES." codeql.yml was not among those four, and the contexts were made
  # required afterwards.
  merge_group:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    # Weekly, so newly-shipped CodeQL queries run against unchanged code (same rationale as the daily
    # pip-audit cron: a fresh finding against a quiet codebase shouldn't wait for the next push).
    - cron: "0 7 * * 1"
  workflow_dispatch:

permissions:
  contents: read

jobs:
  analyze:
    name: CodeQL (${{ matrix.language }})
    # ONLY on this repo — it is public, so code scanning is free; anywhere else (a fork, or the retired
    # private archive) it would need paid GHAS, so this stays a skipped no-op there. (GitHub Actions
    # string == is case-insensitive.)
    if: github.repository == 'MEFORORG/MessageFoundry'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write # upload the SARIF results to code scanning
      actions: read
    strategy:
      fail-fast: false
      matrix:
        # python = the engine; javascript-typescript = the ide/ VS Code extension (both ship to the
        # mirror). Both are interpreted — CodeQL needs no build step. Drop a language to narrow scope.
        language: [python, javascript-typescript]
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false # CodeQL uploads via the job token, not a persisted git credential
      - name: Initialize CodeQL
        uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
        with:
          languages: ${{ matrix.language }}
          # security-extended adds higher-recall security queries on top of the default suite.
          queries: security-extended
      - name: Analyze
        uses: github/codeql-action/analyze@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
        with:
          category: "/language:${{ matrix.language }}"