Pre-release quality: fix formatting, sync documentation, restructure user guide, and port template improvements

.github/pull_request_template.md

@@ -27,7 +27,10 @@ Before submitting this pull request, ensure you have completed the following:
 ### Build and Test
 
 - [ ] Code builds successfully: `dotnet build --configuration Release`
-- [ ] All tests pass: `dotnet test --configuration Release`
+- [ ] All unit tests pass: `dotnet test --configuration Release`
+- [ ] Self-validation tests pass:
+  `dotnet run --project src/DemaConsulting.SpdxTool --configuration Release --framework net10.0`
+  `--no-build -- --validate`
 - [ ] Code produces zero warnings
 
 ### Code Quality
@@ -42,7 +45,7 @@ Please run the following checks before submitting:
 
 - [ ] **Spell checker passes**: `cspell "**/*.{md,cs}"`
 - [ ] **Markdown linter passes**: `markdownlint "**/*.md"`
-- [ ] **YAML linter passes**: `yamllint '**/*.{yml,yaml}'`
+- [ ] **YAML linter passes**: `yamllint .`
 
 ### Testing
 

CONTRIBUTING.md

@@ -91,16 +91,14 @@ Before submitting your changes, run the following checks:
 
 ```bash
 # Build the project
-dotnet build
+dotnet build --configuration Release
 
-# Run all tests
-dotnet test
+# Run unit tests
+dotnet test --configuration Release
 
-# Run code analysis (warnings will be treated as errors)
-dotnet build /p:TreatWarningsAsErrors=true
-
-# Run self-validation
-dotnet run --project src/DemaConsulting.SpdxTool -- --validate
+# Run self-validation tests
+dotnet run --project src/DemaConsulting.SpdxTool \
+  --configuration Release --framework net10.0 --no-build -- --validate
 
 # Generate code coverage (optional)
 dotnet test --collect:"XPlat Code Coverage"
@@ -165,20 +163,30 @@ The CI pipeline will also run markdown linting and spell checking on all documen
 
 ### Running Tests
 
+#### Unit Tests
+
 ```bash
-# Run all tests
-dotnet test
+# Run all unit tests
+dotnet test --configuration Release
 
 # Run tests for a specific framework
-dotnet test --framework net8.0
+dotnet test --configuration Release --framework net8.0
 
-# Run tests with detailed output
-dotnet test --verbosity detailed
+# Run specific unit test
+dotnet test --filter "FullyQualifiedName~YourTestName"
 
 # Run tests with coverage
 dotnet test --collect:"XPlat Code Coverage"
 ```
 
+#### Self-Validation Tests
+
+```bash
+# Run self-validation tests
+dotnet run --project src/DemaConsulting.SpdxTool \
+  --configuration Release --framework net10.0 --no-build -- --validate
+```
+
 ## Submitting Changes
 
 ### Before Submitting
@@ -221,11 +229,10 @@ dotnet test --collect:"XPlat Code Coverage"
 Releases are managed by project maintainers following these steps:
 
 1. Update version numbers in project files
-2. Update CHANGELOG.md with release notes
-3. Create a release branch
-4. Tag the release
-5. Build and publish NuGet packages
-6. Create a GitHub release with release notes
+2. Create a release branch
+3. Tag the release
+4. Build and publish NuGet packages
+5. Create a GitHub release with auto-generated build notes
 
 Contributors do not need to worry about versioning or releases.
 

README.md

@@ -94,22 +94,27 @@ Running self-validation produces a report containing the following information:
 
 | Information         | Value                                              |
 | :------------------ | :------------------------------------------------- |
-| SpdxTool Version    | <version>                                         |
+| SpdxTool Version    | <version>                                          |
 | Machine Name        | <machine-name>                                     |
 | OS Version          | <os-version>                                       |
 | DotNet Runtime      | <dotnet-runtime-version>                           |
 | Time Stamp          | <timestamp>                                        |
 
 Tests:
 
-- AddPackage: Passed
-- AddRelationship: Passed
-- CopyPackage: Passed
-- FindPackage: Passed
-- GetVersion: Passed
-- Query: Passed
-- RenameId: Passed
-- UpdatePackage: Passed
+- SpdxTool_AddPackage: Passed
+- SpdxTool_AddRelationship: Passed
+- SpdxTool_Validate: Passed
+- SpdxTool_CopyPackage: Passed
+- SpdxTool_Diagram: Passed
+- SpdxTool_FindPackage: Passed
+- SpdxTool_GetVersion: Passed
+- SpdxTool_Hash: Passed
+- SpdxTool_Ntia: Passed
+- SpdxTool_Query: Passed
+- SpdxTool_RenameId: Passed
+- SpdxTool_ToMarkdown: Passed
+- SpdxTool_UpdatePackage: Passed
 
 Validation Passed
 ```

docs/guide/guide.md

@@ -6,39 +6,16 @@ software development and compliance workflows.
 
 ## Purpose
 
-SpdxTool simplifies the process of working with SPDX SBOM files by:
-
-* Providing command-line utilities for SPDX document manipulation
-* Enabling workflow automation through YAML configuration files
-* Supporting comprehensive SBOM operations (create, read, update, validate)
-* Facilitating compliance and security analysis
-* Enabling integration with CI/CD pipelines
+SpdxTool simplifies the process of working with SPDX SBOM files by providing a rich command-line interface for
+document manipulation, YAML-based workflow automation for complex multi-step operations, and comprehensive SBOM
+operations including package management, relationship management, validation, markdown export, and mermaid diagram
+generation. It facilitates compliance and security analysis and integrates with CI/CD pipelines. A built-in
+self-validation system supports tool qualification in regulated environments.
 
 ## Scope
 
-This guide covers the installation, configuration, and usage of SpdxTool, including:
-
-* Installation prerequisites and methods
-* Command-line interface and general syntax
-* Core commands for SPDX operations
-* Workflow files for automation
-* Self-validation capabilities
-* CI/CD integration with GitHub Actions and Azure DevOps
-* Common use cases and examples
-* Best practices for SPDX document management, workflows, and security
-* Troubleshooting and debug techniques
-* Reference materials and additional resources
-
-## Key Features
-
-* **Command-Line Interface**: Rich set of commands for SPDX operations
-* **Workflow Automation**: YAML-based workflow files for complex operations
-* **SPDX Validation**: Validate SPDX documents for correctness and NTIA compliance
-* **Package Management**: Add, update, copy, and query packages
-* **Relationship Management**: Manage relationships between SPDX elements
-* **Markdown Export**: Generate human-readable markdown from SPDX documents
-* **Mermaid Diagrams**: Visualize SPDX relationships as diagrams
-* **Self-Validation**: Built-in validation for tool qualification
+This guide covers the installation, configuration, and usage of SpdxTool from command-line basics through
+workflow automation, CI/CD integration, and best practices for SPDX document management.
 
 # Installation
 
@@ -517,14 +494,19 @@ Example validation report:
 
 Tests:
 
-- AddPackage: Passed
-- AddRelationship: Passed
-- CopyPackage: Passed
-- FindPackage: Passed
-- GetVersion: Passed
-- Query: Passed
-- RenameId: Passed
-- UpdatePackage: Passed
+- SpdxTool_AddPackage: Passed
+- SpdxTool_AddRelationship: Passed
+- SpdxTool_Validate: Passed
+- SpdxTool_CopyPackage: Passed
+- SpdxTool_Diagram: Passed
+- SpdxTool_FindPackage: Passed
+- SpdxTool_GetVersion: Passed
+- SpdxTool_Hash: Passed
+- SpdxTool_Ntia: Passed
+- SpdxTool_Query: Passed
+- SpdxTool_RenameId: Passed
+- SpdxTool_ToMarkdown: Passed
+- SpdxTool_UpdatePackage: Passed
 
 Validation Passed
 ```
@@ -552,10 +534,10 @@ jobs:
   validate:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Setup .NET
-        uses: actions/setup-dotnet@v4
+        uses: actions/setup-dotnet@v5
         with:
           dotnet-version: '8.x'
 

docs/spdx-tool-and-sbom-tool.md

@@ -42,7 +42,7 @@ This example workflow:
 
 ```yaml
     - name: Setup dotnet
-      uses: actions/setup-dotnet@v4
+      uses: actions/setup-dotnet@v5
       with:
         dotnet-version: 8.x
 

docs/spdx-tool-command-line.md

@@ -29,13 +29,17 @@ Usage: spdx-tool [options] <command> [arguments]
 Options:
   -h, --help                               Show this help message and exit
   -v, --version                            Show version information and exit
+  -l, --log <log-file>                     Log output to file
+  -s, --silent                             Silence console output
+      --validate                           Perform self-validation
+  -r, --result <file>                      Self-validation result TRX file
 
 Commands:
   help <command>                           Display extended help about a command
   add-package                              Add package to SPDX document (workflow only).
   add-relationship <spdx.json> <args>      Add relationship between elements.
   copy-package <spdx.json> <args>          Copy package between SPDX documents (workflow only).
-  diagram <spdx.json> <mermaid.txt>        Generate mermaid diagram.
+  diagram <spdx.json> <mermaid.txt> [tools] Generate mermaid diagram.
   find-package <spdx.json> <criteria>      Find package ID in SPDX document
   get-version <spdx.json> <criteria>       Get the version of an SPDX package.
   hash <operation> <algorithm> <file>      Generate or verify hashes of files

docs/spdx-tool-github-ci.md

@@ -33,7 +33,7 @@ The GitHub Actions workflow file should have a step to ensure dotnet is installe
 
 ```yaml
     - name: Setup dotnet 8
-      uses: actions/setup-dotnet@v4
+      uses: actions/setup-dotnet@v5
       with:
         dotnet-version: 8.x
 ```
@@ -50,7 +50,7 @@ The GitHub Actions workflow file should have a step to restore dotnet tools spec
 
 ## Run SPDX Tool Step
 
-The Github Actions workflow file should have a step to run SPDX Tool. For example:
+The GitHub Actions workflow file should have a step to run SPDX Tool. For example:
 
 ```yaml
     - name: Run SBOM Workflow

src/DemaConsulting.SpdxTool/SelfValidation/ValidateDiagram.cs

@@ -39,7 +39,7 @@ public static void Run(Context context, TestResults.TestResults results)
 
         // Report validation result to console
         context.WriteLine($"- SpdxTool_Diagram: {(passed ? "Passed" : "Failed")}");
-        
+
         // Add validation result to test results collection
         results.Results.Add(
             new TestResult

src/DemaConsulting.SpdxTool/SelfValidation/ValidateHash.cs

@@ -39,7 +39,7 @@
 
         // Report validation result to console
         context.WriteLine($"- SpdxTool_Hash: {(passed ? "Passed" : "Failed")}");
-        
+
         // Add validation result to test results collection
         results.Results.Add(
             new TestResult
@@ -61,7 +61,7 @@
         try
         {
             // Create the temporary validation folder
             Directory.CreateDirectory("validate.tmp");
 
             // Run both generation and verification validation tests
             return DoValidateGenerate() && DoValidateVerify();
@@ -107,7 +107,7 @@
 
         // Read the generated hash value
         var hash = File.ReadAllText("validate.tmp/test-file.txt.sha256");
-        
+
         // Verify hash matches expected SHA256 value for the test content
         return hash == "d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592";
     }

src/DemaConsulting.SpdxTool/SelfValidation/ValidateToMarkdown.cs

@@ -39,7 +39,7 @@ public static void Run(Context context, TestResults.TestResults results)
 
         // Report validation result to console
         context.WriteLine($"- SpdxTool_ToMarkdown: {(passed ? "Passed" : "Failed")}");
-        
+
         // Add validation result to test results collection
         results.Results.Add(
             new TestResult

test/DemaConsulting.SpdxTool.Tests/DemaConsulting.SpdxTool.Tests.csproj

@@ -1,6 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
+    <!-- Build Configuration -->
     <TargetFrameworks>net8.0;net9.0;net10.0</TargetFrameworks>
     <LangVersion>12</LangVersion>
     <ImplicitUsings>enable</ImplicitUsings>
@@ -9,15 +10,16 @@
     <!-- Test Project Configuration -->
     <IsPackable>false</IsPackable>
     <IsTestProject>true</IsTestProject>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
 
     <!-- Code Quality Configuration -->
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
-    <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
     <EnableNETAnalyzers>true</EnableNETAnalyzers>
     <AnalysisLevel>latest</AnalysisLevel>
   </PropertyGroup>
 
+  <!-- Test Framework Dependencies -->
   <ItemGroup>
     <PackageReference Include="coverlet.collector" Version="8.0.0">
       <PrivateAssets>all</PrivateAssets>
@@ -26,6 +28,10 @@
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.0.1" />
     <PackageReference Include="MSTest.TestAdapter" Version="4.1.0" />
     <PackageReference Include="MSTest.TestFramework" Version="4.1.0" />
+  </ItemGroup>
+
+  <!-- Code Analysis Dependencies -->
+  <ItemGroup>
     <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="10.0.103">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
@@ -36,6 +42,7 @@
     </PackageReference>
   </ItemGroup>
 
+  <!-- Project References -->
   <ItemGroup>
     <ProjectReference Include="..\..\src\DemaConsulting.SpdxTool\DemaConsulting.SpdxTool.csproj">
       <Private>true</Private>