Apply test naming convention, improve README, and add requirements traceability

.config/dotnet-tools.json

@@ -37,6 +37,12 @@
       "commands": [
         "versionmark"
       ]
+    },
+    "demaconsulting.reqstream": {
+      "version": "1.3.0",
+      "commands": [
+        "reqstream"
+      ]
     }
   }
 }

.cspell.json

@@ -37,10 +37,12 @@
     "markdownlint",
     "mermaid",
     "msbuild",
+    "MSBUILDDISABLENODEREUSE",
     "mstest",
     "myterm",
     "ncipollo",
     "NOASSERTION",
+    "NTIA",
     "nuget",
     "nupkg",
     "opencover",
@@ -57,6 +59,7 @@
     "Semgrep",
     "semver",
     "SPDXID",
+    "SPWF",
     "spdxmodel",
     "slnx",
     "snupkg",

.github/workflows/build.yaml

@@ -76,6 +76,8 @@ jobs:
           --no-restore
           --verbosity normal
           --filter "TestCategory=AnyOS|TestCategory=Windows"
+          --logger "trx;LogFilePrefix=windows"
+          --results-directory test-results
 
       - name: Run Linux Tests
         if: startsWith(matrix.os, 'ubuntu')
@@ -85,6 +87,8 @@ jobs:
           --no-restore
           --verbosity normal
           --filter "TestCategory=AnyOS|TestCategory=Linux"
+          --logger "trx;LogFilePrefix=ubuntu"
+          --results-directory test-results
 
       - name: Create Dotnet Tool
         run: |
@@ -98,6 +102,12 @@ jobs:
           path: |
             pack/*.nupkg
 
+      - name: Upload Test Results
+        uses: actions/upload-artifact@v7
+        with:
+          name: test-results-${{ matrix.os }}
+          path: test-results/*.trx
+
       - name: Capture tool versions
         shell: bash
         run: |
@@ -137,6 +147,13 @@ jobs:
           pattern: 'version-capture-*'
         continue-on-error: true
 
+      - name: Download all test results
+        uses: actions/download-artifact@v8
+        with:
+          path: test-results
+          pattern: 'test-results-*'
+        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.
@@ -189,6 +206,16 @@ jobs:
           echo "=== Build Notes Report ==="
           cat docs/buildnotes.md
 
+      - name: Generate Requirements with ReqStream
+        shell: bash
+        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
+
       - name: Publish Tool Versions
         shell: bash
         run: |
@@ -227,6 +254,36 @@ jobs:
           --metadata date="$(date +'%Y-%m-%d')"
           --output docs/guide/guide.html
 
+      - 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 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 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
+
       # === GENERATE PDF DOCUMENTS WITH WEASYPRINT ===
       # This section converts HTML documents to PDF using Weasyprint.
       # Downstream projects: Add any additional Weasyprint PDF generation steps here.
@@ -245,6 +302,27 @@ jobs:
           docs/guide/guide.html
           "docs/SpdxWorkflows User Guide.pdf"
 
+      - name: Generate Requirements PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          --pdf-variant pdf/a-3u
+          docs/requirements/requirements.html
+          "docs/SpdxWorkflows Requirements.pdf"
+
+      - name: Generate Requirements Justifications PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          --pdf-variant pdf/a-3u
+          docs/justifications/justifications.html
+          "docs/SpdxWorkflows Requirements Justifications.pdf"
+
+      - name: Generate Trace Matrix PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          --pdf-variant pdf/a-3u
+          docs/tracematrix/tracematrix.html
+          "docs/SpdxWorkflows Trace Matrix.pdf"
+
       # === UPLOAD ARTIFACTS ===
       # This section uploads all generated documentation artifacts.
       # Downstream projects: Add any additional artifact uploads here.

README.md

@@ -1,11 +1,46 @@
-# Spdx Workflows
+# SpdxWorkflows
 
-This repository contains standard SpdxTool workflow files.
+[![GitHub forks][badge-forks]][link-forks]
+[![GitHub stars][badge-stars]][link-stars]
+[![GitHub contributors][badge-contributors]][link-contributors]
+[![License][badge-license]][link-license]
+[![Build][badge-build]][link-build]
 
-These files can be executed using the following SpdxTool workflow steps:
+DEMA Consulting collection of standard [SpdxTool][link-spdxtool] workflow YAML files for
+capturing build-tool version information and populating [SPDX][link-spdx] software bills of
+materials (SBOMs).
+
+## Features
+
+This collection provides:
+
+- **Version Discovery Workflows**: Detect and capture the installed versions of common build
+  tools — .NET SDK, GCC, MSBuild, NuGet, VSTest, and IAR EW ARM
+- **SPDX Package Workflows**: Add build-tool packages to an SPDX document — .NET SDK, GCC,
+  MSBuild, NuGet, VSTest, and IAR EW ARM
+- **NuGet SPDX Enhancement**: Enrich an SPDX document package with metadata sourced from a
+  NuGet package's own SPDX document
+- **Multi-Platform Support**: Workflows target Windows and Linux build environments
+- **MSTest V4**: Modern unit testing with MSTest framework version 4
+- **Comprehensive CI/CD**: GitHub Actions workflows with quality checks and builds
+
+## Installation
+
+SpdxWorkflows are referenced directly by URL inside your own SpdxTool workflow YAML files.
+No separate installation step is required beyond having SpdxTool available.
+
+Install SpdxTool using the .NET CLI:
+
+```bash
+dotnet tool install --global DemaConsulting.SpdxTool
+```
+
+## Usage
+
+Reference a workflow by supplying its versioned GitHub URL and an optional SHA-512 integrity
+hash to the `run-workflow` command:
 
 ```yaml
-  # Run GetDotNetVersion workflow
 - command: run-workflow
   inputs:
     url: 'https://github.com/demaconsulting/SpdxWorkflows/blob/0.1.0/GetDotNetVersion.yaml'
@@ -15,3 +50,85 @@ These files can be executed using the following SpdxTool workflow steps:
     outputs:
       <optional outputs>
 ```
+
+Replace `0.1.0` with the desired release tag. See [Releases][link-releases] for available
+versions and their workflow integrity hashes.
+
+## Available Workflows
+
+### Version Discovery
+
+These workflows detect and capture the installed version of a build tool. All version
+discovery workflows produce a single `version` output parameter.
+
+| Workflow | Description | Platform |
+| --- | --- | --- |
+| [GetDotNetVersion.yaml][link-wf-getdotnet] | Gets the installed .NET SDK version | Windows, Linux |
+| [GetGccVersion.yaml][link-wf-getgcc] | Gets the installed GCC version | Linux |
+| [GetIarEwArmVersion.yaml][link-wf-getiar] | Gets the installed IAR EW ARM version | Windows |
+| [GetMsBuildVersion.yaml][link-wf-getmsbuild] | Gets the installed MSBuild version | Windows |
+| [GetNugetVersion.yaml][link-wf-getnuget] | Gets the installed NuGet version | Windows |
+| [GetNugetPackagePath.yaml][link-wf-getnugetpath] | Gets the path to a NuGet package in the local cache | Windows |
+| [GetVsTestVersion.yaml][link-wf-getvstest] | Gets the installed VSTest version | Windows |
+
+### SPDX Package Addition
+
+These workflows add a build-tool entry as a package to an existing SPDX document.
+
+| Workflow | Description | Platform |
+| --- | --- | --- |
+| [AddDotNetPackage.yaml][link-wf-adddotnet] | Adds the .NET SDK package to an SPDX document | Windows, Linux |
+| [AddGccPackage.yaml][link-wf-addgcc] | Adds the GCC package to an SPDX document | Linux |
+| [AddIarEwArmPackage.yaml][link-wf-addiar] | Adds the IAR EW ARM package to an SPDX document | Windows |
+| [AddMsBuildPackage.yaml][link-wf-addmsbuild] | Adds the MSBuild package to an SPDX document | Windows |
+| [AddNugetPackage.yaml][link-wf-addnuget] | Adds the NuGet package to an SPDX document | Windows |
+| [AddVsTestPackage.yaml][link-wf-addvstest] | Adds the VSTest package to an SPDX document | Windows |
+| [EnhancePackageFromNugetSpdx.yaml][link-wf-enhance] | Enhances an SPDX package with metadata from a NuGet SPDX document | Windows |
+
+For full parameter and output details see the [User Guide][link-guide].
+
+## Documentation
+
+- **[User Guide][link-guide]**: Workflow parameters, outputs, and usage examples
+
+## License
+
+Copyright (c) DEMA Consulting. Licensed under the MIT License. See [LICENSE][link-license] for
+details.
+
+By contributing to this project, you agree that your contributions will be licensed under the
+MIT License.
+
+<!-- Badge references -->
+[badge-forks]: https://img.shields.io/github/forks/demaconsulting/SpdxWorkflows?style=plastic
+[badge-stars]: https://img.shields.io/github/stars/demaconsulting/SpdxWorkflows?style=plastic
+[badge-contributors]: https://img.shields.io/github/contributors/demaconsulting/SpdxWorkflows?style=plastic
+[badge-license]: https://img.shields.io/github/license/demaconsulting/SpdxWorkflows?style=plastic
+[badge-build]: https://img.shields.io/github/actions/workflow/status/demaconsulting/SpdxWorkflows/build_on_push.yaml?style=plastic
+
+<!-- Link references -->
+[link-forks]: https://github.com/demaconsulting/SpdxWorkflows/network/members
+[link-stars]: https://github.com/demaconsulting/SpdxWorkflows/stargazers
+[link-contributors]: https://github.com/demaconsulting/SpdxWorkflows/graphs/contributors
+[link-license]: LICENSE
+[link-build]: https://github.com/demaconsulting/SpdxWorkflows/actions/workflows/build_on_push.yaml
+[link-releases]: https://github.com/demaconsulting/SpdxWorkflows/releases
+[link-guide]: docs/guide/guide.md
+[link-spdxtool]: https://github.com/demaconsulting/SpdxTool
+[link-spdx]: https://spdx.dev
+
+<!-- Workflow file references -->
+[link-wf-getdotnet]: https://github.com/demaconsulting/SpdxWorkflows/blob/main/GetDotNetVersion.yaml
+[link-wf-getgcc]: https://github.com/demaconsulting/SpdxWorkflows/blob/main/GetGccVersion.yaml
+[link-wf-getiar]: https://github.com/demaconsulting/SpdxWorkflows/blob/main/GetIarEwArmVersion.yaml
+[link-wf-getmsbuild]: https://github.com/demaconsulting/SpdxWorkflows/blob/main/GetMsBuildVersion.yaml
+[link-wf-getnuget]: https://github.com/demaconsulting/SpdxWorkflows/blob/main/GetNugetVersion.yaml
+[link-wf-getnugetpath]: https://github.com/demaconsulting/SpdxWorkflows/blob/main/GetNugetPackagePath.yaml
+[link-wf-getvstest]: https://github.com/demaconsulting/SpdxWorkflows/blob/main/GetVsTestVersion.yaml
+[link-wf-adddotnet]: https://github.com/demaconsulting/SpdxWorkflows/blob/main/AddDotNetPackage.yaml
+[link-wf-addgcc]: https://github.com/demaconsulting/SpdxWorkflows/blob/main/AddGccPackage.yaml
+[link-wf-addiar]: https://github.com/demaconsulting/SpdxWorkflows/blob/main/AddIarEwArmPackage.yaml
+[link-wf-addmsbuild]: https://github.com/demaconsulting/SpdxWorkflows/blob/main/AddMsBuildPackage.yaml
+[link-wf-addnuget]: https://github.com/demaconsulting/SpdxWorkflows/blob/main/AddNugetPackage.yaml
+[link-wf-addvstest]: https://github.com/demaconsulting/SpdxWorkflows/blob/main/AddVsTestPackage.yaml
+[link-wf-enhance]: https://github.com/demaconsulting/SpdxWorkflows/blob/main/EnhancePackageFromNugetSpdx.yaml

docs/justifications/definition.yaml

@@ -0,0 +1,11 @@
+---
+resource-path:
+  - docs/justifications
+  - docs/template
+input-files:
+  - docs/justifications/title.txt
+  - docs/justifications/introduction.md
+  - docs/justifications/justifications.md
+template: template.html
+table-of-contents: true
+number-sections: true

docs/justifications/introduction.md

@@ -0,0 +1,26 @@
+# Introduction
+
+This document contains the justifications for the requirements of the SpdxWorkflows project.
+
+## Purpose
+
+This justifications document provides the rationale behind each requirement in the SpdxWorkflows
+project. Each requirement justification explains why the requirement exists, what problem it
+solves, and how it contributes to the overall value of the workflows.
+
+## Scope
+
+This document covers justifications for:
+
+- Version discovery workflow requirements
+- Package addition workflow requirements
+- Package enhancement workflow requirements
+
+## Audience
+
+This document is intended for:
+
+- Software developers understanding design decisions
+- Quality assurance teams reviewing requirement rationale
+- Project stakeholders evaluating project scope
+- Compliance and audit teams reviewing requirements traceability

docs/justifications/title.txt

@@ -0,0 +1,13 @@
+---
+title: SpdxWorkflows Requirements Justifications
+subtitle: Requirements Justifications for SpdxWorkflows
+author: DEMA Consulting
+description: Requirements Justifications for the SpdxWorkflows project
+lang: en-US
+keywords:
+  - SpdxWorkflows
+  - Requirements
+  - Justifications
+  - SPDX
+  - Workflows
+---

docs/requirements/definition.yaml

@@ -0,0 +1,11 @@
+---
+resource-path:
+  - docs/requirements
+  - docs/template
+input-files:
+  - docs/requirements/title.txt
+  - docs/requirements/introduction.md
+  - docs/requirements/requirements.md
+template: template.html
+table-of-contents: true
+number-sections: true

docs/requirements/introduction.md

@@ -0,0 +1,26 @@
+# Introduction
+
+This document contains the requirements for the SpdxWorkflows project.
+
+## Purpose
+
+SpdxWorkflows is a collection of standard SpdxTool workflow files for generating SPDX
+software bill of materials documents. It provides reusable workflows for capturing version
+information and adding package entries for common build tools.
+
+## Scope
+
+This requirements document covers:
+
+- Version discovery workflows for build tools
+- Package addition workflows for SPDX documents
+- Package enhancement workflows from NuGet SPDX data
+
+## Audience
+
+This document is intended for:
+
+- Software developers working on SpdxWorkflows
+- Quality assurance teams validating requirements
+- Project stakeholders reviewing project scope
+- Users understanding the workflows' capabilities