build.yaml

---
on:
  workflow_call:
    inputs:
      version:
        required: true
        type: string
    secrets:
      SONAR_TOKEN:
        required: true

jobs:
  # Performs quick quality checks for project formatting consistency including
  # markdown linting, spell checking, and YAML validation.
  quality-checks:
    name: Quality Checks
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      # === INSTALL DEPENDENCIES ===
      # This section installs all required dependencies for quality checks.

      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup dotnet
        uses: actions/setup-dotnet@v5
        with:
          dotnet-version: 10.x

      - name: Restore Tools
        run: >
          dotnet tool restore

      # === CAPTURE TOOL VERSIONS ===
      # This section captures the versions of all tools used in the quality checks.

      - name: Capture tool versions
        shell: bash
        run: |
          mkdir -p artifacts
          echo "Capturing tool versions..."
          dotnet versionmark --capture --job-id "quality" \
            --output "artifacts/versionmark-quality.json" -- \
            dotnet git versionmark
          echo "✓ Tool versions captured"

      # === CAPTURE OTS SELF-VALIDATION RESULTS ===
      # This section captures self-validation results from OTS tools.

      - name: Run VersionMark self-validation
        run: dotnet versionmark --validate --results artifacts/versionmark-self-validation-quality.trx

      # === RUN QUALITY CHECKS ===
      # This section runs all quality checks for the project.

      - name: Run markdown linter
        uses: DavidAnson/markdownlint-cli2-action@v22
        with:
          globs: '**/*.md'

      - name: Run spell checker
        uses: streetsidesoftware/cspell-action@v8
        with:
          files: '**/*.{md,cs}'
          incremental_files_only: false

      - name: Run YAML linter
        uses: ibiqlik/action-yamllint@v3
        with:
          config_file: .yamllint.yaml

      # === UPLOAD ARTIFACTS ===
      # This section uploads all quality artifacts.

      - name: Upload quality artifacts
        uses: actions/upload-artifact@v7
        with:
          name: artifacts-quality
          path: artifacts/

  # Builds and unit-tests the project on supported operating systems with SonarCloud analysis.
  build:
    name: Build ${{ matrix.os }}
    needs: quality-checks
    permissions:
      contents: read       # To read repository contents
      pull-requests: write  # To write pull requests analysis results and artifacts

    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest, macos-latest]

    runs-on: ${{ matrix.os }}

    steps:

      # === INSTALL DEPENDENCIES ===
      # This section installs all required dependencies for the build.

      - name: Checkout
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Setup dotnet
        uses: actions/setup-dotnet@v5
        with:
          dotnet-version: |
            8.x
            9.x
            10.x

      - name: Restore Tools
        run: >
          dotnet tool restore

      # === CAPTURE TOOL VERSIONS ===
      # This section captures the versions of all tools used in the build process.

      - name: Capture tool versions
        shell: bash
        run: |
          mkdir -p artifacts
          echo "Capturing tool versions..."
          # Create short job ID: build-windows, build-ubuntu, build-macos
          OS_SHORT=$(echo "${{ matrix.os }}" | sed 's/-latest//')
          JOB_ID="build-${OS_SHORT}"
          dotnet versionmark --capture --job-id "${JOB_ID}" \
            --output "artifacts/versionmark-${JOB_ID}.json" -- \
            dotnet git dotnet-sonarscanner versionmark
          echo "✓ Tool versions captured"

      # === CAPTURE OTS SELF-VALIDATION RESULTS ===
      # This section captures self-validation results from OTS tools.

      - name: Run VersionMark self-validation
        run: dotnet versionmark --validate --results artifacts/versionmark-self-validation-${{ matrix.os }}.trx

      # === BUILD AND TEST ===
      # This section builds and tests the project.

      - name: Restore Dependencies
        run: >
          dotnet restore

      - name: Start Sonar Scanner
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: >
          dotnet dotnet-sonarscanner
          begin
          /k:"demaconsulting_SonarMark"
          /o:"demaconsulting"
          /d:sonar.token="${{ secrets.SONAR_TOKEN }}"
          /d:sonar.host.url="https://sonarcloud.io"
          /d:sonar.cs.opencover.reportsPaths=**/*.opencover.xml
          /d:sonar.scanner.scanAll=false

      - name: Build
        run: >
          dotnet build
          --no-restore
          --configuration Release
          --property:Version=${{ inputs.version }}

      - name: Test
        run: >
          dotnet test
          --no-build
          --configuration Release
          --property:Version=${{ inputs.version }}
          --collect "XPlat Code Coverage;Format=opencover"
          --logger "trx;LogFilePrefix=${{ matrix.os }}"
          --results-directory artifacts

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

      - name: Create Dotnet Tool
        run: >
          dotnet pack
          --no-build
          --no-restore
          --property:PackageVersion=${{ inputs.version }}

      # === UPLOAD ARTIFACTS ===
      # This section uploads all build artifacts.

      - name: Upload build artifacts
        uses: actions/upload-artifact@v7
        with:
          name: artifacts-build-${{ matrix.os }}
          path: artifacts/

      - name: Upload packages
        uses: actions/upload-artifact@v7
        with:
          name: packages-${{ matrix.os }}
          path: |
            src/DemaConsulting.SonarMark/bin/Release/*.nupkg
            src/DemaConsulting.SonarMark/bin/Release/*.snupkg

  # Performs security analysis using CodeQL.
  codeql:
    name: CodeQL Analysis
    runs-on: ubuntu-latest
    needs: quality-checks
    permissions:
      actions: read
      contents: read
      security-events: write

    steps:
      # === INSTALL DEPENDENCIES ===
      # This section installs all required dependencies for CodeQL analysis.

      - name: Checkout
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Initialize CodeQL
        uses: github/codeql-action/init@v4
        with:
          languages: csharp
          build-mode: manual
          queries: security-and-quality
          config-file: ./.github/codeql-config.yml

      - name: Setup dotnet
        uses: actions/setup-dotnet@v5
        with:
          dotnet-version: |
            8.x
            9.x
            10.x

      - name: Restore Tools
        run: >
          dotnet tool restore

      - name: Restore Dependencies
        run: >
          dotnet restore

      # === BUILD AND ANALYZE ===
      # This section builds the project and runs CodeQL analysis.

      - name: Build
        run: >
          dotnet build
          --no-restore
          --configuration Release
          --property:Version=${{ inputs.version }}

      - name: Perform CodeQL Analysis
        uses: github/codeql-action/analyze@v4
        with:
          category: "/language:csharp"
          output: artifacts
          upload: false

      # === UPLOAD ARTIFACTS ===
      # This section uploads all CodeQL artifacts.

      - name: Upload CodeQL artifacts
        uses: actions/upload-artifact@v7
        with:
          name: artifacts-codeql
          path: artifacts/

  # Tests the packaged tool on multiple OS and .NET versions.
  integration-test:
    name: Integration Test ${{ matrix.os }} .NET ${{ matrix.dotnet-version }}
    runs-on: ${{ matrix.os }}
    needs: build
    permissions:
      contents: read

    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest, macos-latest]
        dotnet-version: ['8.x', '9.x', '10.x']

    steps:
      # === INSTALL DEPENDENCIES ===
      # This section installs all required dependencies and tools for integration testing.

      - name: Checkout
        uses: actions/checkout@v6
        with:
          sparse-checkout: |
            .versionmark.yaml
            .config/dotnet-tools.json

      - name: Download package
        uses: actions/download-artifact@v8
        with:
          name: packages-${{ matrix.os }}
          path: packages

      - name: Setup dotnet
        uses: actions/setup-dotnet@v5
        with:
          dotnet-version: ${{ matrix.dotnet-version }}

      - name: Restore Tools
        run: >
          dotnet tool restore

      - name: Install tool from package
        shell: bash
        run: |
          echo "Installing package version ${{ inputs.version }} from: packages/"
          dotnet tool install --global \
            --add-source packages \
            --version ${{ inputs.version }} \
            DemaConsulting.SonarMark

      # === CAPTURE TOOL VERSIONS ===
      # This section captures the versions of all tools used in the integration tests.

      - name: Capture tool versions
        shell: bash
        run: |
          mkdir -p artifacts
          echo "Capturing tool versions..."
          # Create short job ID: int-windows-8, int-ubuntu-9, int-macos-10, etc.
          OS_SHORT=$(echo "${{ matrix.os }}" | sed 's/-latest//')
          DOTNET_SHORT=$(echo "${{ matrix.dotnet-version }}" | sed 's/\.x$//')
          JOB_ID="int-${OS_SHORT}-${DOTNET_SHORT}"
          dotnet versionmark --capture --job-id "${JOB_ID}" \
            --output "artifacts/versionmark-${JOB_ID}.json" -- \
            dotnet git versionmark
          echo "✓ Tool versions captured"

      # === RUN INTEGRATION TESTS ===
      # This section runs the integration tests for the tool.

      - name: Test version display
        shell: bash
        run: |
          echo "Testing sonarmark --version..."
          sonarmark --version || { echo "✗ Version command failed"; exit 1; }
          echo "✓ Version command succeeded"

      - name: Test help display
        shell: bash
        run: |
          echo "Testing sonarmark --help..."
          sonarmark --help || { echo "✗ Help command failed"; exit 1; }
          echo "✓ Help command succeeded"

      - name: Test SonarMark analysis generation
        shell: bash
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        run: |
          echo "Testing sonarmark analysis generation..."
          sonarmark \
            --server https://sonarcloud.io \
            --project-key demaconsulting_SonarMark \
            --branch ${{ github.ref_name }} \
            --token "$SONAR_TOKEN" \
            --report analysis-report-${{ matrix.os }}-${{ matrix.dotnet-version }}.md \
            || { echo "✗ Analysis generation failed"; exit 1; }
          echo "✓ Analysis generation succeeded"

          # Verify report file was created
          if [ ! -f "analysis-report-${{ matrix.os }}-${{ matrix.dotnet-version }}.md" ]; then
            echo "✗ Report file was not created"
            exit 1
          fi
          echo "✓ Report file exists"

          # Display report summary
          echo "Report summary:"
          cat "analysis-report-${{ matrix.os }}-${{ matrix.dotnet-version }}.md"

      - name: Run SonarMark self-validation
        shell: bash
        run: |
          echo "Running SonarMark self-validation..."
          sonarmark --validate \
            --results artifacts/sonarmark-self-validation-${{ matrix.os }}-dotnet${{ matrix.dotnet-version }}.trx \
            || { echo "✗ Self-validation failed"; exit 1; }
          echo "✓ Self-validation succeeded"

      # === UPLOAD ARTIFACTS ===
      # This section uploads all generated artifacts for use by downstream jobs.

      - name: Upload validation artifacts
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: artifacts-validation-${{ matrix.os }}-dotnet${{ matrix.dotnet-version }}
          path: artifacts/

  # Generates all documentation including requirements, trace matrix, and build notes.
  build-docs:
    name: Build Documentation
    runs-on: windows-latest
    needs: [build, integration-test, codeql]
    permissions:
      contents: read

    steps:
      # === CHECKOUT AND DOWNLOAD ARTIFACTS ===
      # This section retrieves the code and all necessary artifacts from previous jobs.

      - name: Checkout
        uses: actions/checkout@v6

      - name: Download all job artifacts
        uses: actions/download-artifact@v8
        with:
          path: artifacts
          pattern: 'artifacts-*'
          merge-multiple: true
        continue-on-error: true

      - name: Download SonarMark package
        uses: actions/download-artifact@v8
        with:
          name: packages-ubuntu-latest
          path: packages

      # === INSTALL DEPENDENCIES ===
      # This section installs all required dependencies and tools for document generation.

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 'lts/*'

      - name: Setup dotnet
        uses: actions/setup-dotnet@v5
        with:
          dotnet-version: 10.x

      - name: Install npm dependencies
        run: npm install

      - name: Install SonarMark from package
        shell: bash
        run: |
          echo "Installing SonarMark version ${{ inputs.version }}"
          dotnet tool install --global \
            --add-source packages \
            --version ${{ inputs.version }} \
            DemaConsulting.SonarMark

      - name: Restore Tools
        run: dotnet tool restore

      # === CAPTURE TOOL VERSIONS ===
      # This section captures the versions of all tools used in the build process.

      - name: Capture tool versions for build-docs
        shell: bash
        run: |
          echo "Capturing tool versions..."
          dotnet versionmark --capture --job-id "build-docs" \
            --output "artifacts/versionmark-build-docs.json" -- \
            dotnet git node npm pandoc weasyprint sarifmark sonarmark reqstream buildmark versionmark
          echo "✓ Tool versions captured"

      # === CAPTURE OTS SELF-VALIDATION RESULTS ===
      # This section captures self-validation results from OTS tools.

      - name: Run ReqStream self-validation
        run: dotnet reqstream --validate --results artifacts/reqstream-self-validation.trx

      - name: Run BuildMark self-validation
        run: dotnet buildmark --validate --results artifacts/buildmark-self-validation.trx

      - name: Run VersionMark self-validation
        run: dotnet versionmark --validate --results artifacts/versionmark-self-validation.trx

      - name: Run SarifMark self-validation
        run: dotnet sarifmark --validate --results artifacts/sarifmark-self-validation.trx

      - name: Run SonarMark self-validation
        run: sonarmark --validate --results artifacts/sonarmark-self-validation.trx

      # === GENERATE MARKDOWN REPORTS ===
      # This section generates all markdown reports from various tools and sources.

      - name: Generate Requirements Report and Trace Matrix
        run: >
          dotnet reqstream
          --requirements requirements.yaml
          --tests "artifacts/**/*.trx"
          --report docs/requirements/requirements.md
          --matrix docs/tracematrix/tracematrix.md
          --justifications docs/justifications/justifications.md
          --enforce

      - name: Generate CodeQL Quality Report with SarifMark
        shell: bash
        run: >
          dotnet sarifmark
          --sarif artifacts/csharp.sarif
          --report docs/quality/codeql-quality.md
          --heading "SonarMark CodeQL Analysis"
          --report-depth 1

      - name: Display CodeQL Quality Report
        shell: bash
        run: |
          echo "=== CodeQL Quality Report ==="
          cat docs/quality/codeql-quality.md

      - name: Generate Code Quality Report with SonarMark
        shell: bash
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        run: >
          sonarmark
          --server https://sonarcloud.io
          --project-key demaconsulting_SonarMark
          --branch ${{ github.ref_name }}
          --token "$SONAR_TOKEN"
          --report docs/quality/sonar-quality.md
          --report-depth 1

      - name: Display SonarCloud Quality Report
        shell: bash
        run: |
          echo "=== SonarCloud Quality Report ==="
          cat docs/quality/sonar-quality.md

      - name: Generate Build Notes with BuildMark
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        shell: bash
        run: >
          dotnet buildmark
          --build-version ${{ inputs.version }}
          --report docs/buildnotes.md
          --report-depth 1

      - name: Display Build Notes Report
        shell: bash
        run: |
          echo "=== Build Notes Report ==="
          cat docs/buildnotes.md

      - name: Publish Tool Versions
        shell: bash
        run: |
          echo "Publishing tool versions..."
          dotnet versionmark --publish --report docs/buildnotes/versions.md --report-depth 1 \
            -- "artifacts/**/versionmark-*.json"
          echo "✓ Tool versions published"

      - name: Display Tool Versions Report
        shell: bash
        run: |
          echo "=== Tool Versions Report ==="
          cat docs/buildnotes/versions.md

      # === GENERATE HTML DOCUMENTS WITH PANDOC ===
      # This section converts markdown documents to HTML using Pandoc.

      - name: Generate Guide HTML with Pandoc
        run: >
          dotnet pandoc
          --defaults docs/guide/definition.yaml
          --filter node_modules/.bin/mermaid-filter.cmd
          --metadata version="${{ inputs.version }}"
          --metadata date="$(date +'%Y-%m-%d')"
          --output docs/guide/guide.html

      - name: Generate Requirements HTML with Pandoc
        run: >
          dotnet pandoc
          --defaults docs/requirements/definition.yaml
          --filter node_modules/.bin/mermaid-filter.cmd
          --metadata version="${{ inputs.version }}"
          --metadata date="$(date +'%Y-%m-%d')"
          --output docs/requirements/requirements.html

      - name: Generate Trace Matrix HTML with Pandoc
        run: >
          dotnet pandoc
          --defaults docs/tracematrix/definition.yaml
          --filter node_modules/.bin/mermaid-filter.cmd
          --metadata version="${{ inputs.version }}"
          --metadata date="$(date +'%Y-%m-%d')"
          --output docs/tracematrix/tracematrix.html

      - name: Generate Justifications HTML with Pandoc
        run: >
          dotnet pandoc
          --defaults docs/justifications/definition.yaml
          --filter node_modules/.bin/mermaid-filter.cmd
          --metadata version="${{ inputs.version }}"
          --metadata date="$(date +'%Y-%m-%d')"
          --output docs/justifications/justifications.html

      - name: Generate Build Notes HTML with Pandoc
        shell: bash
        run: >
          dotnet pandoc
          --defaults docs/buildnotes/definition.yaml
          --metadata version="${{ inputs.version }}"
          --metadata date="$(date +'%Y-%m-%d')"
          --filter node_modules/.bin/mermaid-filter.cmd
          --output docs/buildnotes/buildnotes.html

      - name: Generate Code Quality HTML with Pandoc
        run: >
          dotnet pandoc
          --defaults docs/quality/definition.yaml
          --filter node_modules/.bin/mermaid-filter.cmd
          --metadata version="${{ inputs.version }}"
          --metadata date="$(date +'%Y-%m-%d')"
          --output docs/quality/quality.html

      # === GENERATE PDF DOCUMENTS WITH WEASYPRINT ===
      # This section converts HTML documents to PDF using Weasyprint.

      - name: Generate Guide PDF with Weasyprint
        run: >
          dotnet weasyprint
          --pdf-variant pdf/a-3u
          docs/guide/guide.html
          "docs/SonarMark User Guide.pdf"

      - name: Generate Requirements PDF with Weasyprint
        run: >
          dotnet weasyprint
          --pdf-variant pdf/a-3u
          docs/requirements/requirements.html
          "docs/SonarMark Requirements.pdf"

      - name: Generate Trace Matrix PDF with Weasyprint
        run: >
          dotnet weasyprint
          --pdf-variant pdf/a-3u
          docs/tracematrix/tracematrix.html
          "docs/SonarMark Trace Matrix.pdf"

      - name: Generate Justifications PDF with Weasyprint
        run: >
          dotnet weasyprint
          --pdf-variant pdf/a-3u
          docs/justifications/justifications.html
          "docs/SonarMark Requirements Justifications.pdf"

      - name: Generate Build Notes PDF with Weasyprint
        run: >
          dotnet weasyprint
          --pdf-variant pdf/a-3u
          docs/buildnotes/buildnotes.html
          "docs/SonarMark Build Notes.pdf"

      - name: Generate Code Quality PDF with Weasyprint
        run: >
          dotnet weasyprint
          --pdf-variant pdf/a-3u
          docs/quality/quality.html
          "docs/SonarMark Code Quality.pdf"

      # === UPLOAD ARTIFACTS ===
      # This section uploads all generated documentation artifacts.

      - name: Upload documentation
        uses: actions/upload-artifact@v7
        with:
          name: documents
          path: |
            docs/*.pdf
            docs/buildnotes.md