sonar.yml

name: sonar

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:

# Cancel superseded runs on the same branch / PR.
concurrency:
  group: sonar-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# Least privilege: the analysis only reads the repository. PR decoration is
# delivered by the SonarQube Cloud GitHub App, not by this workflow's token.
permissions:
  contents: read

env:
  DOTNET_NOLOGO: 'true'
  DOTNET_CLI_TELEMETRY_OPTOUT: 'true'
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 'true'

jobs:
  analyze:
    name: SonarQube Cloud analysis
    runs-on: ubuntu-latest
    # Scanner + build + test + coverage is ~3 min; cap a stuck analysis well above that.
    timeout-minutes: 20
    # PRs opened from a fork cannot read SONAR_TOKEN; skip the analysis there rather
    # than fail. Branches in this repository (the normal case) run normally.
    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          # Full history lets Sonar attribute issues via git blame and detect new code.
          fetch-depth: 0

      - name: Setup .NET
        uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68 # v6.0.0
        with:
          dotnet-version: '10.0.x'

      - name: Setup Java
        # The SonarScanner for .NET runs on the JVM; SonarQube Cloud requires Java 17+.
        uses: actions/setup-java@03ad4de0992f5dab5e18fcb136590ce7c4a0ac95 # v5
        with:
          distribution: temurin
          java-version: '17'

      - name: Cache SonarQube Cloud packages
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
        with:
          path: ~/.sonar/cache
          key: ${{ runner.os }}-sonar
          restore-keys: ${{ runner.os }}-sonar

      - name: Install SonarScanner for .NET
        run: |
          dotnet tool install --global dotnet-sonarscanner
          echo "$HOME/.dotnet/tools" >> "$GITHUB_PATH"

      # The build must sit between `begin` and `end`: the scanner hooks MSBuild to
      # observe the compilation, so it cannot use a pre-built or --no-build output.
      # *.verified.* are Verify snapshot oracles — generated test fixtures, not production source. Excluding them
      # keeps Sonar from analysing the emitted HTML/JS/Markdown as if it were hand-written code (and from counting
      # the near-identical snapshots as duplication).
      # The Benchmarks project is a measurement harness, never shipped and never unit-tested: excluding it from
      # COVERAGE (not from analysis) keeps the new-code coverage gate about the library, while its code still
      # gets the SonarAnalyzer pass.
      #
      # Two shell rules are declined for every *.sh in the repository (policy: ADR-0060). They are ignored HERE,
      # rather than in .editorconfig like the declined Roslyn rules, because they are SonarQube's own analysis
      # rather than compiler diagnostics the scanner republishes — nothing the build does can silence them.
      #   S7682 ("add an explicit return at the end of the function") — every function it flags ends with the
      #     command whose status IS the function's result: a `cat` heredoc, an `awk` invocation, a `printf`, or
      #     in one case an `exit`, after which a return is unreachable. `return 0` would mask those failures and
      #     a bare `return` restates the default, so the rule can only make the scripts worse or longer.
      #   S7679 ("assign this positional parameter to a local variable") — every script here is `#!/bin/sh`, and
      #     `local` is not POSIX. tools/trains.sh already shows the price of obeying without it: the one helper
      #     that needed named parameters carries `_tf_`-prefixed globals instead. Paying that in every two-line
      #     helper, to name a `$1` sitting one line below the function's own name, buys nothing.
      - name: Begin analysis
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        run: >-
          dotnet-sonarscanner begin
          /k:"reefact_first-class-errors"
          /o:"reefact"
          /d:sonar.token="$SONAR_TOKEN"
          /d:sonar.host.url="https://sonarcloud.io"
          /d:sonar.cs.opencover.reportsPaths="artifacts/coverage/**/coverage.opencover.xml"
          /d:sonar.exclusions="**/*.verified.*"
          /d:sonar.coverage.exclusions="FirstClassErrors.RequestBinder.Benchmarks/**"
          /d:sonar.issue.ignore.multicriteria="s7682,s7679"
          /d:sonar.issue.ignore.multicriteria.s7682.ruleKey="shelldre:S7682"
          /d:sonar.issue.ignore.multicriteria.s7682.resourceKey="**/*.sh"
          /d:sonar.issue.ignore.multicriteria.s7679.ruleKey="shelldre:S7679"
          /d:sonar.issue.ignore.multicriteria.s7679.resourceKey="**/*.sh"

      - name: Build
        # Disable the CI warning ratchet (Directory.Build.props) for the analysis build only. The scanner
        # needs this compilation to COMPLETE so it can collect the SonarAnalyzer diagnostics and upload them
        # in `end`. The scanner already neutralises TreatWarningsAsErrors, but not MSBuildTreatWarningsAsErrors
        # — which also promotes compiler/analyzer warnings — so a Sonar rule warning would fail this build
        # before results are reported. The ratchet stays enforced by ci.yml (both OS legs), which is the gate;
        # this analysis leg is not.
        run: dotnet build FirstClassErrors.sln -c Release -p:TreatWarningsAsErrors=false -p:MSBuildTreatWarningsAsErrors=false

      - name: Test with coverage
        # Reuse coverage.runsettings so the OpenCover report matches the one the ci workflow produces.
        run: >-
          dotnet test FirstClassErrors.sln -c Release --no-build
          --collect:"XPlat Code Coverage"
          --settings coverage.runsettings
          --results-directory artifacts/coverage
          --logger "console;verbosity=normal"

      - name: End analysis
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        run: dotnet-sonarscanner end /d:sonar.token="$SONAR_TOKEN"