# CodeQL Security Analysis Workflow Template
# ==========================================
#
# This template sets up CodeQL code scanning for security vulnerabilities.
#
# How to use:
# -----------
# 1. Copy this file to .github/workflows/codeql-analysis.yml in your repo
# 2. Update the languages array based on your repo (python, javascript, typescript, etc.)
# 3. Customize paths to analyze if needed
# 4. Commit and push - CodeQL will run automatically
#
# What is CodeQL?
# --------------
# CodeQL is GitHub's semantic code analysis engine that finds security vulnerabilities
# and coding errors. It's free for public repos and GitHub Enterprise.
#
# Supported languages:
# -------------------
# - python
# - javascript (includes TypeScript)
# - go
# - java
# - csharp
# - cpp
# - ruby
# - swift

name: CodeQL Security Analysis

on:
  push:
    branches:
      - main
      - develop
  pull_request:
    branches:
      - main
      - develop
  schedule:
    # Run CodeQL analysis every Monday at 00:00 UTC
    - cron: '0 0 * * 1'
  workflow_dispatch:

# Limit concurrent runs
concurrency:
  group: codeql-${{ github.ref }}
  cancel-in-progress: true

jobs:
  analyze:
    name: CodeQL Analysis
    runs-on: ubuntu-latest
    timeout-minutes: 30

    permissions:
      # Required for CodeQL to upload results
      actions: read
      contents: read
      security-events: write

    strategy:
      fail-fast: false
      matrix:
        # Update this array based on your repository's languages
        # For BlackRoad OS backend: ['python', 'javascript']
        # For frontend only: ['javascript']
        language: ['python', 'javascript']

    steps:
      # ========================================
      # 1. Checkout code
      # ========================================
      - name: Checkout repository
        uses: actions/checkout@v4

      # ========================================
      # 2. Initialize CodeQL
      # ========================================
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v3
        with:
          languages: ${{ matrix.language }}
          # If you want to analyze specific paths only:
          # paths:
          #   - backend/
          #   - src/
          # paths-ignore:
          #   - tests/
          #   - '**/*.test.js'

      # ========================================
      # 3. Build code (if needed)
      # ========================================
      # For compiled languages (Java, C#, C++), add build steps here
      # For interpreted languages (Python, JavaScript), auto-build works

      # Autobuild attempts to build any compiled languages
      - name: Autobuild
        uses: github/codeql-action/autobuild@v3

      # Alternative: Manual build steps for Python if needed
      # - name: Build Python (manual)
      #   if: matrix.language == 'python'
      #   run: |
      #     python -m pip install --upgrade pip
      #     pip install -r backend/requirements.txt

      # ========================================
      # 4. Perform CodeQL Analysis
      # ========================================
      - name: Perform CodeQL Analysis
        uses: github/codeql-action/analyze@v3
        with:
          category: "/language:${{ matrix.language }}"

# ========================================
# Workflow Summary
# ========================================
#
# This workflow:
# 1. Runs on push, PR, schedule (weekly), and manual dispatch
# 2. Analyzes code for security vulnerabilities using CodeQL
# 3. Uploads results to GitHub Security tab
# 4. Creates alerts for any issues found
#
# View results:
# - Go to your repository → Security tab → Code scanning alerts
#
# Customization:
# - Add more languages to matrix.language array
# - Filter paths to analyze specific directories
# - Adjust schedule frequency
# - Add custom queries for domain-specific security checks