build.yaml

---
# Reusable workflow for building VHDLTest artifacts
# This workflow is called by other workflows to build the project
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.
      # Downstream projects: Add any additional dependency installations here.

      - 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 build process.
      # Downstream projects: Add any additional tools to capture here.

      - 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.
      # Downstream projects: Add any additional self-validation steps here.

      - 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.
      # Downstream projects: Add any additional quality checks here.

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

      - name: Run spell checker
        uses: streetsidesoftware/cspell-action@v8
        with:
          incremental_files_only: false
          config: .cspell.json
          files: |
            **/*.md
            **/*.cs
            **/*.yaml
            **/*.yml

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

      - 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 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: [ubuntu-latest, windows-latest, macos-latest]

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

    steps:

      # === INSTALL DEPENDENCIES ===
      # This section installs all required dependencies for the build.
      # Downstream projects: Add any additional dependency installations here.

      - 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

      - uses: msys2/setup-msys2@v2
        if: matrix.os == 'windows-latest'
        with:
          msystem: MINGW64
          update: true

      - uses: nickg/setup-nvc-ci@v1
        if: matrix.os != 'macos-latest'
        with:
          version: latest

      - name: Install NVC (macOS)
        if: matrix.os == 'macos-latest'
        run: brew install nvc

      - name: Restore Tools
        run: >
          dotnet tool restore

      # === CAPTURE TOOL VERSIONS ===
      # This section captures the versions of all tools used in the build process.
      # Downstream projects: Add any additional tools to capture here.

      - 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.
      # Downstream projects: Add any additional self-validation steps here.

      - 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.
      # Downstream projects: Add any additional build and test steps here.

      - name: Restore Dependencies
        run: >
          dotnet restore

      - name: Start Sonar Scanner
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: >
          dotnet dotnet-sonarscanner
          begin
          /k:"demaconsulting_VHDLTest"
          /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.
      # Downstream projects: Add any additional artifact uploads here.

      - 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.VHDLTest/bin/Release/*.nupkg
            src/DEMAConsulting.VHDLTest/bin/Release/*.snupkg

  # Performs integration testing on GHDL simulator across a matrix of operating
  # systems and .NET runtimes to ensure compatibility with the GHDL simulator.
  test-ghdl:
    name: Test on GHDL
    # Permissions for this job
    permissions:
      contents: read  # To read repository contents

    needs: build

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

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

    steps:

      # === INSTALL DEPENDENCIES ===
      # This section installs all required dependencies for GHDL integration testing.
      # Downstream projects: Add any additional dependency installations here.

      - uses: actions/checkout@v6

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

      - uses: msys2/setup-msys2@v2
        if: matrix.os == 'windows-latest'
        with:
          msystem: MINGW64
          update: true

      - uses: ghdl/setup-ghdl@v1
        with:
          version: 5.1.1
          backend: ${{ matrix.os == 'macos-latest' && 'llvm' || 'mcode' }}

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

      - name: Install VHDLTest
        shell: bash
        run: >
          dotnet tool install
          --global DemaConsulting.VHDLTest
          --add-source packages
          --version ${{ inputs.version }}

      # === CAPTURE TOOL VERSIONS ===
      # This section captures the versions of all tools used in the integration tests.
      # Downstream projects: Add any additional tools to capture here.

      - name: Restore Tools
        run: >
          dotnet tool restore

      - name: Capture tool versions
        shell: bash
        run: |
          mkdir -p artifacts
          echo "Capturing tool versions..."
          # Create appropriate job ID for the test job
          OS_SHORT=$(echo "${{ matrix.os }}" | sed 's/-latest//')
          DOTNET_SHORT=$(echo "${{ matrix.dotnet }}" | sed 's/\.x$//')
          SIMULATOR="ghdl"
          JOB_ID="int-${SIMULATOR}-${OS_SHORT}-${DOTNET_SHORT}"
          dotnet versionmark --capture --job-id "${JOB_ID}" \
            --output "artifacts/versionmark-${JOB_ID}.json" -- \
            dotnet git versionmark ghdl
          echo "✓ Tool versions captured"

      # === RUN INTEGRATION TESTS ===
      # This section runs the integration tests for VHDLTest with the GHDL simulator.
      # Downstream projects: Add any additional integration test steps here.

      - name: Validate VHDLTest
        shell: bash
        run: >
          vhdltest --validate --simulator ghdl
          --results artifacts/ghdl-${{ matrix.os }}-dotnet${{ matrix.dotnet }}-validation.trx
          && echo "Validation completed successfully"

      - name: Run
        working-directory: test/example
        shell: bash
        run: |
          # Run the test
          bash ./test.sh ghdl

      # === UPLOAD ARTIFACTS ===
      # This section uploads all generated artifacts for use by downstream jobs.
      # Downstream projects: Add any additional artifact uploads here.

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

  # Performs integration testing on NVC simulator across a matrix of operating
  # systems and .NET runtimes to ensure compatibility with the NVC simulator.
  test-nvc:
    name: Test on NVC
    # Permissions for this job
    permissions:
      contents: read  # To read repository contents

    needs: build

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

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

    steps:

      # === INSTALL DEPENDENCIES ===
      # This section installs all required dependencies for NVC integration testing.
      # Downstream projects: Add any additional dependency installations here.

      - uses: actions/checkout@v6

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

      - uses: msys2/setup-msys2@v2
        if: matrix.os == 'windows-latest'
        with:
          msystem: MINGW64
          update: true

      - uses: nickg/setup-nvc-ci@v1
        if: matrix.os != 'macos-latest'
        with:
          version: latest

      - name: Install NVC (macOS)
        if: matrix.os == 'macos-latest'
        run: brew install nvc

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

      - name: Install VHDLTest
        shell: bash
        run: >
          dotnet tool install
          --global DemaConsulting.VHDLTest
          --add-source packages
          --version ${{ inputs.version }}

      # === CAPTURE TOOL VERSIONS ===
      # This section captures the versions of all tools used in the integration tests.
      # Downstream projects: Add any additional tools to capture here.

      - name: Restore Tools
        run: >
          dotnet tool restore

      - name: Capture tool versions
        shell: bash
        run: |
          mkdir -p artifacts
          echo "Capturing tool versions..."
          # Create appropriate job ID for the test job
          OS_SHORT=$(echo "${{ matrix.os }}" | sed 's/-latest//')
          DOTNET_SHORT=$(echo "${{ matrix.dotnet }}" | sed 's/\.x$//')
          SIMULATOR="nvc"
          JOB_ID="int-${SIMULATOR}-${OS_SHORT}-${DOTNET_SHORT}"
          dotnet versionmark --capture --job-id "${JOB_ID}" \
            --output "artifacts/versionmark-${JOB_ID}.json" -- \
            dotnet git versionmark nvc
          echo "✓ Tool versions captured"

      # === RUN INTEGRATION TESTS ===
      # This section runs the integration tests for VHDLTest with the NVC simulator.
      # Downstream projects: Add any additional integration test steps here.

      - name: Validate VHDLTest
        shell: bash
        run: >
          vhdltest --validate --simulator nvc
          --results artifacts/nvc-${{ matrix.os }}-dotnet${{ matrix.dotnet }}-validation.trx
          && echo "Validation completed successfully"

      - name: Run
        working-directory: test/example
        shell: bash
        run: |
          # Run the test
          bash ./test.sh nvc

      # === UPLOAD ARTIFACTS ===
      # This section uploads all generated artifacts for use by downstream jobs.
      # Downstream projects: Add any additional artifact uploads here.

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

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

    steps:
      # === INSTALL DEPENDENCIES ===
      # This section installs all required dependencies for CodeQL analysis.
      # Downstream projects: Add any additional dependency installations here.

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

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

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

      - 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.
      # Downstream projects: Add any additional analysis steps here.

      - 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.
      # Downstream projects: Add any additional artifact uploads here.

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

  # 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, test-ghdl, test-nvc, codeql]

    permissions:
      contents: read

    steps:
      # === CHECKOUT AND DOWNLOAD ARTIFACTS ===
      # This section retrieves the code and all necessary artifacts from previous jobs.
      # Downstream projects: Add any additional artifact downloads here.

      - 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

      # === INSTALL DEPENDENCIES ===
      # This section installs all required dependencies and tools for document generation.
      # Downstream projects: Add any additional dependency installations here.

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

      - name: Restore Tools
        run: dotnet tool restore

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

      - name: Install npm dependencies
        run: npm install

      # === CAPTURE TOOL VERSIONS ===
      # This section captures the versions of all tools used in the build process.
      # Downstream projects: Add any additional tools to capture here.

      - name: Capture tool versions for build-docs
        shell: bash
        run: |
          mkdir -p artifacts
          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.
      # Downstream projects: Add any additional self-validation steps here.

      - 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: dotnet sonarmark --validate --results artifacts/sonarmark-self-validation.trx

      # === GENERATE MARKDOWN REPORTS ===
      # This section generates all markdown reports from various tools and sources.
      # Downstream projects: Add any additional markdown report generation steps here.

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

      - name: Build Requirements PDF 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: Convert Requirements HTML to PDF with Weasyprint
        run: >
          dotnet weasyprint
          --pdf-variant pdf/a-3u
          docs/requirements/requirements.html
          "docs/VHDLTest Requirements.pdf"

      - name: Build Justifications PDF 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: Convert Justifications HTML to PDF with Weasyprint
        run: >
          dotnet weasyprint
          --pdf-variant pdf/a-3u
          docs/justifications/justifications.html
          "docs/VHDLTest Requirements Justifications.pdf"

      - name: Build Trace Matrix PDF 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: Convert Trace Matrix HTML to PDF with Weasyprint
        run: >
          dotnet weasyprint
          --pdf-variant pdf/a-3u
          docs/tracematrix/tracematrix.html
          "docs/VHDLTest Trace Matrix.pdf"

      - name: Build PDF 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: Convert HTML to PDF with Weasyprint
        run: >
          dotnet weasyprint
          --pdf-variant pdf/a-3u
          docs/guide/guide.html
          "docs/VHDLTest User Guide.pdf"

      - name: Generate CodeQL Quality Report with SarifMark
        run: >
          dotnet sarifmark
          --sarif artifacts/csharp.sarif
          --report docs/quality/codeql-quality.md
          --heading "VHDLTest 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: >
          dotnet sonarmark
          --server https://sonarcloud.io
          --project-key demaconsulting_VHDLTest
          --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 Code Quality HTML with Pandoc
        shell: bash
        run: >
          dotnet pandoc
          --defaults docs/quality/definition.yaml
          --metadata version="${{ inputs.version }}"
          --metadata date="$(date +'%Y-%m-%d')"
          --output docs/quality/quality.html

      - name: Convert Code Quality HTML to PDF with Weasyprint
        run: >
          dotnet weasyprint
          --pdf-variant pdf/a-3u
          docs/quality/quality.html
          "docs/VHDLTest Code Quality.pdf"

      - 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

      - 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: Convert Build Notes HTML to PDF with Weasyprint
        run: >
          dotnet weasyprint
          --pdf-variant pdf/a-3u
          docs/buildnotes/buildnotes.html
          "docs/VHDLTest Build Notes.pdf"

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