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:
      - 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

      - name: Capture tool versions
        shell: bash
        run: |
          dotnet versionmark --capture --job-id "quality" -- dotnet git versionmark

      - name: Upload version capture
        uses: actions/upload-artifact@v7
        with:
          name: version-capture-quality
          path: versionmark-quality.json

      - 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

  # Builds and unit-tests the project on supported operating systems to ensure
  # unit-tests operate on all platforms and to run SonarScanner for generating
  # the code quality report.
  build:
    name: Build ${{ matrix.os }}
    needs: quality-checks
    permissions:
      contents: read
      pull-requests: write

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

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

    steps:

      - 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

      - name: Restore Dependencies
        run: >
          dotnet restore

      - name: Start Sonar Scanner
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: >
          dotnet dotnet-sonarscanner
          begin
          /k:"demaconsulting_VersionMark"
          /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 test-results

      - 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 }}

      - name: Upload Test Results
        uses: actions/upload-artifact@v7
        with:
          name: test-results-${{ matrix.os }}
          path: test-results/*.trx

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

  # Runs CodeQL security and quality analysis, gathering results to include
  # in the code quality report.
  codeql:
    name: CodeQL Analysis
    runs-on: ubuntu-latest
    needs: quality-checks
    permissions:
      actions: read
      contents: read
      security-events: write

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

      - name: Initialize CodeQL
        uses: github/codeql-action/init@v4
        with:
          languages: csharp
          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

      - 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: sarif-results
          upload: false

      - name: Upload CodeQL SARIF
        uses: actions/upload-artifact@v7
        with:
          name: codeql-sarif
          path: sarif-results/csharp.sarif

  # Performs integration testing on a matrix of operating systems and .NET runtimes,
  # involving basic tool execution and running self-validation to ensure compatibility
  # across different platforms and runtime 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]
        dotnet-version: ['8.x', '9.x', '10.x']

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


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

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

      - 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.VersionMark

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

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

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

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

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

      - name: Upload version capture
        uses: actions/upload-artifact@v7
        with:
          name: version-capture-${{ matrix.os }}-dotnet${{ matrix.dotnet-version }}
          path: versionmark-int-*.json

  # Builds the supporting documentation including user guides, requirements,
  # trace matrices, code quality reports, and build notes.
  build-docs:
    name: Build Documents
    runs-on: windows-latest
    needs: [build, integration-test, codeql]
    permissions:
      contents: read

    steps:
      - name: Checkout
        uses: actions/checkout@v6

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

      - name: Download all test results
        uses: actions/download-artifact@v8
        with:
          path: test-results
          pattern: '*test-results*'
        continue-on-error: true

      - name: Download VersionMark package
        uses: actions/download-artifact@v8
        with:
          name: artifacts-windows-latest
          path: packages

      - name: Download CodeQL SARIF
        uses: actions/download-artifact@v8
        with:
          name: codeql-sarif
          path: codeql-results

      - name: Download all version captures
        uses: actions/download-artifact@v8
        with:
          path: version-captures
          pattern: 'version-capture-*'
        continue-on-error: true

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

      - name: Install npm dependencies
        run: npm install

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

      - name: Restore Tools
        run: dotnet tool restore

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

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

      - name: Generate CodeQL Quality Report with SarifMark
        run: >
          dotnet sarifmark
          --sarif codeql-results/csharp.sarif
          --report docs/quality/codeql-quality.md
          --heading "VersionMark 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 SonarCloud Quality Report
        shell: bash
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        run: >
          dotnet sonarmark
          --server https://sonarcloud.io
          --project-key demaconsulting_VersionMark
          --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
        shell: bash
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        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..."
          versionmark --publish --report docs/buildnotes/versions.md --report-depth 1 \
            -- "versionmark-*.json" "version-captures/**/versionmark-*.json"
          echo "✓ Tool versions published"

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

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

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

      - name: Generate Guide HTML with Pandoc
        shell: bash
        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 Guide PDF with Weasyprint
        run: >
          dotnet weasyprint
          --pdf-variant pdf/a-3u
          docs/guide/guide.html
          "docs/VersionMark User Guide.pdf"

      - name: Generate Code Quality HTML with Pandoc
        shell: bash
        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

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

      - name: Generate Requirements HTML with Pandoc
        shell: bash
        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 Requirements PDF with Weasyprint
        run: >
          dotnet weasyprint
          --pdf-variant pdf/a-3u
          docs/requirements/requirements.html
          "docs/VersionMark Requirements.pdf"

      - name: Generate Requirements Justifications HTML with Pandoc
        shell: bash
        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 Requirements Justifications PDF with Weasyprint
        run: >
          dotnet weasyprint
          --pdf-variant pdf/a-3u
          docs/justifications/justifications.html
          "docs/VersionMark Requirements Justifications.pdf"

      - name: Generate Trace Matrix HTML with Pandoc
        shell: bash
        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 Trace Matrix PDF with Weasyprint
        run: >
          dotnet weasyprint
          --pdf-variant pdf/a-3u
          docs/tracematrix/tracematrix.html
          "docs/VersionMark Trace Matrix.pdf"

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