ci.yml

---
# CI (Continuous Integration)
# Purpose: Unified development pipeline covering Code Quality, Testing, and Security Auditing.
# Trigger: Every push and PR on non-main branches.
# Design:
#   - Sequential execution: Lint -> Test -> Audit.
#   - Fail-fast: Stop early if early stages fail to save resources.
#   - Secure: Runs in the context of the triggered ref, avoiding workflow_run risks.

name: "🔄 Continuous Integration"

"on":
  pull_request:
    branches:
      - "main"
      - "dev"
    types: [opened, synchronize, reopened]
  workflow_dispatch:

permissions:
  contents: read

env:
  UNIRTM_LOCKED: 1
  # Opt into Node.js 24 now ahead of GitHub's June 16, 2026 forced migration.
  # See: https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "1"

jobs:
  # 0. Security Guard Stage (PR Only)
  dependency-review:
    name: "🛡️ Dependency Review"
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: "🔒 Harden Runner"
        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
        with:
          disable-sudo: true
          egress-policy: block
          allowed-endpoints: >
            *.aquasecurity.github.io:443
            *.azurecr.io:443
            *.centos.org:443
            *.debian.org:443
            *.debian.org:80
            *.dkr.ecr.*.amazonaws.com:443
            *.gcr.io:443
            *.githubusercontent.com:443
            *.pkg.dev:443
            *.quay.io:443
            *.redhat.com:443
            *.rockylinux.org:443
            *.sigstore.dev:443
            *.ubuntu.com:443
            *.ubuntu.com:80
            api.github.com:443
            api.osv.dev:443
            api.securityscorecards.dev:443
            auth.docker.io:443
            cdn.deno.land:443
            deno.land:443
            dl-cdn.alpinelinux.org:443
            downloads.gradle-dn.com:443
            downloads.gradle.org:443
            files.pythonhosted.org:443
            formulae.brew.sh:443
            get.trivy.dev:443
            ghcr.io:443
            github.com:443
            index.crates.io:443
            index.docker.io:443
            nodejs.org:443
            oss-fuzz-build-logs.storage.googleapis.com:443
            osv-vulnerabilities.storage.googleapis.com:443
            packages.microsoft.com:443
            packagist.org:443
            pkg-containers.githubusercontent.com:443
            production.cloudflare.docker.com:443
            proxy.golang.org:443
            public.ecr.aws:443
            pypi.org:443
            registry-1.docker.io:443
            registry.npmjs.org:443
            registry.terraform.io:443
            registry.yarnpkg.com:443
            repo.maven.apache.org:443
            repo.yarnpkg.com:443
            rubygems.org:443
            services.gradle.org:443
            static.rust-lang.org:443
            sum.golang.org:443
            www.bestpractices.dev:443
            storage.googleapis.com:443
            go.dev:443
            golang.org:443
            *.actions.githubusercontent.com:443
            *.blob.core.windows.net:443
      - name: "📂 Checkout Repository Code"
        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false

      - name: "🔍 Dependency Review"
        if: github.event_name == 'pull_request'
        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0

  # 1. Code Quality Stage (Lint)
  lint:
    name: "🛡️ Quality Assurance Gate (${{ matrix.os }})"
    needs: [dependency-review]
    runs-on: ${{ matrix.os }}
    environment: development
    concurrency:
      group: lint-${{ github.workflow }}-${{ matrix.os }}-${{ github.event.pull_request.number || github.ref }}
      cancel-in-progress: true
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    permissions:
      contents: read
      security-events: write
    timeout-minutes: 60
    env:
      VENV: ".venv"
      PYTHONUTF8: 1
      STEP_SECURITY_DISABLE: ${{ matrix.os != 'ubuntu-latest' }}
    steps:
      - name: "🔒 Harden Runner"
        if: matrix.os == 'ubuntu-latest'
        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
        with:
          disable-sudo: true
          egress-policy: block
          allowed-endpoints: >
            *.aquasecurity.github.io:443
            *.azurecr.io:443
            *.centos.org:443
            *.debian.org:443
            *.debian.org:80
            *.dkr.ecr.*.amazonaws.com:443
            *.gcr.io:443
            *.githubusercontent.com:443
            *.pkg.dev:443
            *.quay.io:443
            *.redhat.com:443
            *.rockylinux.org:443
            *.sigstore.dev:443
            *.ubuntu.com:443
            *.ubuntu.com:80
            api.github.com:443
            api.osv.dev:443
            api.securityscorecards.dev:443
            auth.docker.io:443
            cdn.deno.land:443
            deno.land:443
            dl-cdn.alpinelinux.org:443
            downloads.gradle-dn.com:443
            downloads.gradle.org:443
            files.pythonhosted.org:443
            formulae.brew.sh:443
            get.trivy.dev:443
            ghcr.io:443
            github.com:443
            index.crates.io:443
            index.docker.io:443
            nodejs.org:443
            oss-fuzz-build-logs.storage.googleapis.com:443
            osv-vulnerabilities.storage.googleapis.com:443
            packages.microsoft.com:443
            packagist.org:443
            pkg-containers.githubusercontent.com:443
            production.cloudflare.docker.com:443
            proxy.golang.org:443
            public.ecr.aws:443
            pypi.org:443
            registry-1.docker.io:443
            registry.npmjs.org:443
            registry.terraform.io:443
            registry.yarnpkg.com:443
            repo.maven.apache.org:443
            repo.yarnpkg.com:443
            rubygems.org:443
            services.gradle.org:443
            static.rust-lang.org:443
            sum.golang.org:443
            www.bestpractices.dev:443
            storage.googleapis.com:443
            go.dev:443
            golang.org:443
            *.actions.githubusercontent.com:443
            *.blob.core.windows.net:443
      - name: "📂 Checkout Repository Code"
        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false

      - name: "⚡ Setup UniRTM"
        uses: snowdreamtech/setup-unirtm@cacfb4d739ee46d4a4b2528b02b508df2f560706 # v0.4.0
        with:
          unirtm-version: "0.5.0"
          install: true
          trust: true
        env:
          GITHUB_TOKEN: ${{ secrets.WORKFLOW_SECRET || secrets.GITHUB_TOKEN }}
      - name: "🔍 Inspect Code Quality (Lint)"
        shell: sh
        run: |
          unirtm exec -- pre-commit run --all-files || {
            echo '⚠️  First pass failed. Running second check...'
            unirtm exec -- pre-commit run --all-files
          }
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          UNIRTM_YES: 1

  # 2. Automated Testing Stage (Test)
  test:
    name: "🧪 Automated Testing Suite (${{ matrix.os }})"
    needs: [lint]
    runs-on: ${{ matrix.os }}
    environment: development
    concurrency:
      group: test-${{ github.workflow }}-${{ matrix.os }}-${{ github.event.pull_request.number || github.ref }}
      cancel-in-progress: true
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    permissions:
      contents: read
      pull-requests: read
    timeout-minutes: 60
    env:
      VENV: ".venv"
      PYTHONUTF8: 1
    steps:
      - name: "🔒 Harden Runner"
        if: matrix.os == 'ubuntu-latest'
        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
        with:
          disable-sudo: true
          egress-policy: block
          allowed-endpoints: >
            *.aquasecurity.github.io:443
            *.azurecr.io:443
            *.centos.org:443
            *.debian.org:443
            *.debian.org:80
            *.dkr.ecr.*.amazonaws.com:443
            *.gcr.io:443
            *.githubusercontent.com:443
            *.pkg.dev:443
            *.quay.io:443
            *.redhat.com:443
            *.rockylinux.org:443
            *.sigstore.dev:443
            *.ubuntu.com:443
            *.ubuntu.com:80
            api.github.com:443
            api.osv.dev:443
            api.securityscorecards.dev:443
            auth.docker.io:443
            cdn.deno.land:443
            deno.land:443
            dl-cdn.alpinelinux.org:443
            downloads.gradle-dn.com:443
            downloads.gradle.org:443
            files.pythonhosted.org:443
            formulae.brew.sh:443
            get.trivy.dev:443
            ghcr.io:443
            github.com:443
            index.crates.io:443
            index.docker.io:443
            nodejs.org:443
            oss-fuzz-build-logs.storage.googleapis.com:443
            osv-vulnerabilities.storage.googleapis.com:443
            packages.microsoft.com:443
            packagist.org:443
            pkg-containers.githubusercontent.com:443
            production.cloudflare.docker.com:443
            proxy.golang.org:443
            public.ecr.aws:443
            pypi.org:443
            registry-1.docker.io:443
            registry.npmjs.org:443
            registry.terraform.io:443
            registry.yarnpkg.com:443
            repo.maven.apache.org:443
            repo.yarnpkg.com:443
            rubygems.org:443
            services.gradle.org:443
            static.rust-lang.org:443
            sum.golang.org:443
            www.bestpractices.dev:443
            storage.googleapis.com:443
            go.dev:443
            golang.org:443
            *.actions.githubusercontent.com:443
            *.blob.core.windows.net:443
      - name: "📂 Checkout Repository Code"
        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false

      - name: "⚡ Setup UniRTM"
        uses: snowdreamtech/setup-unirtm@cacfb4d739ee46d4a4b2528b02b508df2f560706 # v0.4.0
        with:
          unirtm-version: "0.5.0"
          install: true
          trust: true
        env:
          GITHUB_TOKEN: ${{ secrets.WORKFLOW_SECRET || secrets.GITHUB_TOKEN }}
      - name: "📦 Cache Language Dependencies (Advanced)"
        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
        with:
          path: |
            ~/go/pkg/mod
            ~/.cache/go-build
            ~/.npm
            ~/.cache/pip
            ~/.cargo/bin
            ~/.cargo/registry/index
            ~/.cargo/registry/cache
            ~/.cargo/git/db
            ~/.bundle/cache
            ~/.composer/cache
            ~/.gradle/caches
            ~/.gradle/wrapper
            ~/.m2/repository
            ~/.pub-cache
            ~/.bun/install/cache
            .build
            _build
            deps
            vendor
            node_modules
            target
          key: ${{ runner.os }}-lang-${{ hashFiles('**/go.mod', '**/package-lock.json', '**/requirements.txt', '**/Cargo.lock', '**/Gemfile.lock', '**/composer.lock', '**/build.gradle*', '**/pom.xml', '**/Package.resolved', '**/pubspec.lock', '**/mix.lock', '**/bun.lockb') }}
          restore-keys: |
            ${{ runner.os }}-lang-

      - name: "🧪 Execute Unit Tests"
        shell: sh
        run: |
          unirtm run test
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          UNIRTM_YES: 1

      - name: "🧪 Execute Shell Tests (Bats)"
        if: matrix.os != 'windows-latest'
        shell: sh
        run: |
          unirtm run test:shell
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          UNIRTM_YES: 1

      - name: "🧪 Execute PowerShell Tests (Pester)"
        if: matrix.os == 'windows-latest'
        shell: pwsh
        run: |
          unirtm run test:powershell
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          UNIRTM_YES: 1

  # 3. Security & Standards Audit Stage (Audit)
  audit:
    name: "🕵️ Security & Standards Audit (ubuntu-latest)"
    needs: [lint]
    runs-on: ubuntu-latest
    environment: development
    concurrency:
      group: audit-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
      cancel-in-progress: true
    permissions:
      contents: read
      pull-requests: read
      statuses: write
      security-events: write
    timeout-minutes: 60
    env:
      VENV: ".venv"
      PYTHONUTF8: 1
    steps:
      - name: "🔒 Harden Runner"
        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
        with:
          disable-sudo: true
          egress-policy: block
          allowed-endpoints: >
            *.aquasecurity.github.io:443
            *.azurecr.io:443
            *.centos.org:443
            *.debian.org:443
            *.debian.org:80
            *.dkr.ecr.*.amazonaws.com:443
            *.gcr.io:443
            *.githubusercontent.com:443
            *.pkg.dev:443
            *.quay.io:443
            *.redhat.com:443
            *.rockylinux.org:443
            *.sigstore.dev:443
            *.ubuntu.com:443
            *.ubuntu.com:80
            api.github.com:443
            api.osv.dev:443
            api.securityscorecards.dev:443
            auth.docker.io:443
            cdn.deno.land:443
            deno.land:443
            dl-cdn.alpinelinux.org:443
            downloads.gradle-dn.com:443
            downloads.gradle.org:443
            files.pythonhosted.org:443
            formulae.brew.sh:443
            get.trivy.dev:443
            ghcr.io:443
            github.com:443
            index.crates.io:443
            index.docker.io:443
            nodejs.org:443
            oss-fuzz-build-logs.storage.googleapis.com:443
            osv-vulnerabilities.storage.googleapis.com:443
            packages.microsoft.com:443
            packagist.org:443
            pkg-containers.githubusercontent.com:443
            production.cloudflare.docker.com:443
            proxy.golang.org:443
            public.ecr.aws:443
            pypi.org:443
            registry-1.docker.io:443
            registry.npmjs.org:443
            registry.terraform.io:443
            registry.yarnpkg.com:443
            repo.maven.apache.org:443
            repo.yarnpkg.com:443
            rubygems.org:443
            services.gradle.org:443
            static.rust-lang.org:443
            sum.golang.org:443
            www.bestpractices.dev:443
            storage.googleapis.com:443
            go.dev:443
            golang.org:443
            *.actions.githubusercontent.com:443
            *.blob.core.windows.net:443
      - name: "📂 Checkout Repository Code"
        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false
          fetch-depth: 0

      - name: "⚡ Setup UniRTM"
        uses: snowdreamtech/setup-unirtm@cacfb4d739ee46d4a4b2528b02b508df2f560706 # v0.4.0
        with:
          unirtm-version: "0.5.0"
          install: true
          trust: true
        env:
          GITHUB_TOKEN: ${{ secrets.WORKFLOW_SECRET || secrets.GITHUB_TOKEN }}
      - name: "📝 Validate Commit Convention (Commitlint)"
        shell: sh
        env:
          EVENT_NAME: ${{ github.event_name }}
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: |


          if [ "$EVENT_NAME" = "pull_request" ]; then
            unirtm exec -- commitlint --from "$BASE_SHA" --to "$HEAD_SHA" --verbose
          else
            unirtm exec -- commitlint --last --verbose
          fi

      - name: "🛡️ Perform Security Audit"
        shell: sh
        run: |
          unirtm run audit
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          TRIVY_CACHE_DIR: .trivycache
          UNIRTM_YES: 1

      - name: "⚡ Cache Documentation Links (Lychee)"
        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
        with:
          path: .lycheecache
          key: ${{ runner.os }}-lychee-${{ hashFiles('**/*.md') }}
          restore-keys: |
            ${{ runner.os }}-lychee-

      - name: "🔗 Verify Documentation Links (Lychee)"
        uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2.8.0
        if: ${{ always() }}
        continue-on-error: true # Don't block CI on link check failures (network issues, rate limits, etc.)
        with:
          args: --config lychee.toml '**/*.md'
          fail: true
        env:
          # Pass GitHub token to avoid rate limiting and access private repos
          GITHUB_TOKEN: ${{ secrets.WORKFLOW_SECRET || secrets.GITHUB_TOKEN }}

      - name: "🕵️ Detect Vulnerabilities (Trivy FS)"
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        if: ${{ always() }}
        env:
          TRIVY_DB_REPOSITORY: "public.ecr.aws/aquasecurity/trivy-db"
          TRIVY_CHECKS_BUNDLE_REPOSITORY: "public.ecr.aws/aquasecurity/trivy-checks"
        with:
          scan-type: "fs"
          ignore-unfixed: true
          format: "sarif"
          output: "trivy-results.sarif"
          severity: "CRITICAL,HIGH,MEDIUM,LOW"
          exit-code: "1"
          skip-dirs: "unirtm_data,cmd/unirtm_data"

      - name: "📤 Upload Security Audit (SARIF)"
        uses: github/codeql-action/upload-sarif@95e58e9a2cdfd71adc6e0353d5c52f41a045d225 # v4.35.2
        if: always()
        with:
          sarif_file: "."