Integrate VersionMark for tool version tracking in Build Notes PDF (#72)

* Initial plan

* Add VersionMark tool and configuration for capturing tool versions

- Add .versionmark.yaml configuration file defining all tools to capture
- Add DemaConsulting.VersionMark v0.1.0 to .config/dotnet-tools.json
- Add version capture steps to all workflow jobs:
  - quality-checks: captures dotnet, git, versionmark
  - build: captures dotnet, git, dotnet-sonarscanner, versionmark
  - integration-test: captures dotnet, git, versionmark
  - build-docs: captures all tools used in documentation generation
- Add version publishing step in build-docs job to generate versions.md
- Add docs/buildnotes/versions.md to buildnotes definition.yaml
- Update .gitignore to exclude versionmark-*.json capture files
- Add 'versionmark' to .cspell.json dictionary

This enables tracking and publishing of tool versions used in each CI/CD job
to the Build Notes PDF documentation, providing complete build environment
transparency.

* Fix versionmark command formatting for consistency and line length

- Remove line continuation in build job versionmark capture (line 148)
- Split build-docs versionmark capture into multiple lines to meet 120 char limit
- Split versionmark publish command into multiple lines for better readability
- Maintain consistent formatting across all versionmark commands in the workflow

* Fix YAML formatting: simplify single-command run statements

- Change 'run: >' to simple 'run:' for single-line dotnet tool restore commands
- Improves consistency with other single-command steps in the workflow
- Addresses code review feedback on YAML style inconsistencies

* Add clarifying comments for version capture patterns

- Document that .NET SDK versions include up to 4 components
- Explain why versionmark captures its own version (complete tool transparency)
- Addresses code review feedback on regex patterns and self-capture rationale

* Fix BuildMark version capture to use --global flag

Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

* Remove BuildMark from integration-test version capture

Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

Author: Copilot

.config/dotnet-tools.json

@@ -49,6 +49,12 @@
       "commands": [
         "sarifmark"
       ]
+    },
+    "demaconsulting.versionmark": {
+      "version": "0.1.0",
+      "commands": [
+        "versionmark"
+      ]
     }
   }
 }

.cspell.json

@@ -36,6 +36,7 @@
     "snupkg",
     "tracematrix",
     "trx",
+    "versionmark",
     "Weasyprint",
     "yamllint"
   ],

.github/workflows/build.yaml

@@ -19,6 +19,28 @@ jobs:
       - 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: |
+          echo "Capturing tool versions..."
+          # Capture versionmark itself for complete tool transparency
+          dotnet versionmark --capture --job-id "quality" -- dotnet git versionmark
+          echo "✓ Tool versions captured"
+
+      - name: Upload version capture
+        uses: actions/upload-artifact@v6
+        with:
+          name: version-capture-quality
+          path: versionmark-quality.json
+
       - name: Run markdown linter
         uses: DavidAnson/markdownlint-cli2-action@v22
         with:
@@ -116,6 +138,22 @@ jobs:
           --no-restore
           --property:PackageVersion=${{ inputs.version }}
 
+      - name: Capture tool versions
+        shell: bash
+        run: |
+          echo "Capturing tool versions..."
+          # Create short job ID: build-win, build-ubuntu
+          OS_SHORT=$(echo "${{ matrix.os }}" | sed 's/windows-latest/win/;s/ubuntu-latest/ubuntu/')
+          JOB_ID="build-${OS_SHORT}"
+          dotnet versionmark --capture --job-id "${JOB_ID}" -- dotnet git dotnet-sonarscanner versionmark
+          echo "✓ Tool versions captured"
+
+      - name: Upload version capture
+        uses: actions/upload-artifact@v6
+        with:
+          name: version-capture-${{ matrix.os }}
+          path: versionmark-build-*.json
+
       - name: Upload Test Results
         uses: actions/upload-artifact@v6
         with:
@@ -201,6 +239,13 @@ jobs:
         dotnet-version: ['8.x', '9.x', '10.x']
 
     steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            .versionmark.yaml
+            .config/dotnet-tools.json
+
       - name: Download package
         uses: actions/download-artifact@v7
         with:
@@ -212,6 +257,9 @@ jobs:
         with:
           dotnet-version: ${{ matrix.dotnet-version }}
 
+      - name: Restore Tools
+        run: dotnet tool restore
+
       - name: Install tool from package
         shell: bash
         run: |
@@ -243,6 +291,23 @@ jobs:
             || { 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}"
+          dotnet versionmark --capture --job-id "${JOB_ID}" -- dotnet git versionmark
+          echo "✓ Tool versions captured"
+
+      - name: Upload version capture
+        uses: actions/upload-artifact@v6
+        with:
+          name: version-capture-${{ matrix.os }}-dotnet${{ matrix.dotnet-version }}
+          path: versionmark-int-*.json
+
       - name: Upload validation test results
         if: always()
         uses: actions/upload-artifact@v6
@@ -307,6 +372,13 @@ jobs:
           name: codeql-sarif
           path: codeql-results
 
+      - name: Download all version captures
+        uses: actions/download-artifact@v7
+        with:
+          path: version-captures
+          pattern: 'version-capture-*'
+        continue-on-error: true
+
       - name: Generate Requirements Report and Trace Matrix
         run: >
           dotnet reqstream
@@ -359,6 +431,31 @@ jobs:
           --report docs/buildnotes.md
           --report-depth 1
 
+      - name: Capture tool versions for build-docs
+        shell: bash
+        run: |
+          echo "Capturing tool versions..."
+          dotnet versionmark --capture --job-id "build-docs" -- \
+            dotnet git node npm pandoc weasyprint \
+            sarifmark sonarmark reqstream buildmark versionmark
+          echo "✓ Tool versions captured"
+
+      - name: Publish Tool Versions
+        shell: bash
+        run: |
+          echo "Publishing tool versions..."
+          dotnet 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: Display Build Notes Report
         shell: bash
         run: |

.gitignore

@@ -38,7 +38,11 @@ docs/quality/sonar-quality.md
 docs/quality/codeql-quality.md
 docs/quality/*.html
 docs/buildnotes.md
+docs/buildnotes/versions.md
 docs/buildnotes/*.html
 
+# VersionMark captures (generated during CI/CD)
+versionmark-*.json
+
 # Agent report files
 AGENT_REPORT_*.md

.versionmark.yaml

@@ -0,0 +1,66 @@
+---
+# VersionMark Configuration File
+# This file defines which tools to capture and how to extract their version information.
+
+tools:
+  # .NET SDK
+  # Note: .NET SDK versions include up to 4 components (e.g., 10.0.102, 8.0.404)
+  dotnet:
+    command: dotnet --version
+    regex: '(?<version>\d+\.\d+\.\d+(?:\.\d+)?)'
+
+  # Git
+  git:
+    command: git --version
+    regex: '(?i)git version (?<version>\d+\.\d+\.\d+)'
+
+  # Node.js
+  node:
+    command: node --version
+    regex: '(?i)v(?<version>\d+\.\d+\.\d+)'
+
+  # npm
+  npm:
+    command: npm --version
+    regex: '(?<version>\d+\.\d+\.\d+)'
+
+  # SonarScanner for .NET (from dotnet tool list)
+  dotnet-sonarscanner:
+    command: dotnet tool list
+    regex: '(?i)dotnet-sonarscanner\s+(?<version>\d+\.\d+\.\d+)'
+
+  # Pandoc (DemaConsulting.PandocTool from dotnet tool list)
+  pandoc:
+    command: dotnet tool list
+    regex: '(?i)demaconsulting\.pandoctool\s+(?<version>\d+\.\d+\.\d+)'
+
+  # WeasyPrint (DemaConsulting.WeasyPrintTool from dotnet tool list)
+  weasyprint:
+    command: dotnet tool list
+    regex: '(?i)demaconsulting\.weasyprinttool\s+(?<version>\d+\.\d+\.\d+)'
+
+  # SarifMark (DemaConsulting.SarifMark from dotnet tool list)
+  sarifmark:
+    command: dotnet tool list
+    regex: '(?i)demaconsulting\.sarifmark\s+(?<version>\d+\.\d+\.\d+)'
+
+  # SonarMark (DemaConsulting.SonarMark from dotnet tool list)
+  sonarmark:
+    command: dotnet tool list
+    regex: '(?i)demaconsulting\.sonarmark\s+(?<version>\d+\.\d+\.\d+)'
+
+  # ReqStream (DemaConsulting.ReqStream from dotnet tool list)
+  reqstream:
+    command: dotnet tool list
+    regex: '(?i)demaconsulting\.reqstream\s+(?<version>\d+\.\d+\.\d+)'
+
+  # BuildMark (DemaConsulting.BuildMark from dotnet tool list --global)
+  # Note: BuildMark is installed globally in integration-test and build-docs jobs
+  buildmark:
+    command: dotnet tool list --global
+    regex: '(?i)demaconsulting\.buildmark\s+(?<version>\d+\.\d+\.\d+)'
+
+  # VersionMark (DemaConsulting.VersionMark from dotnet tool list)
+  versionmark:
+    command: dotnet tool list
+    regex: '(?i)demaconsulting\.versionmark\s+(?<version>\d+\.\d+\.\d+)'

docs/buildnotes/definition.yaml

@@ -7,6 +7,7 @@ input-files:
   - docs/buildnotes/title.txt
   - docs/buildnotes/introduction.md
   - docs/buildnotes.md
+  - docs/buildnotes/versions.md
 
 template: template.html