diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index ad3c25c..561250d 100644 --- a/.github/pull_request_template.md +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e875235..e4cecc1 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/README.md b/README.md index 4ed0890..22dc61f 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,7 @@ Running self-validation produces a report containing the following information: | Information | Value | | :------------------ | :------------------------------------------------- | -| SpdxTool Version | | +| SpdxTool Version | | | Machine Name | | | OS Version | | | DotNet Runtime | | @@ -102,14 +102,19 @@ Running self-validation produces a report containing the following information: 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 ``` diff --git a/docs/guide/guide.md b/docs/guide/guide.md index 4fc05ef..8d3e03f 100644 --- a/docs/guide/guide.md +++ b/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' diff --git a/docs/spdx-tool-and-sbom-tool.md b/docs/spdx-tool-and-sbom-tool.md index 766270d..5a6b496 100644 --- a/docs/spdx-tool-and-sbom-tool.md +++ b/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 diff --git a/docs/spdx-tool-command-line.md b/docs/spdx-tool-command-line.md index 7e9996c..1621bbf 100644 --- a/docs/spdx-tool-command-line.md +++ b/docs/spdx-tool-command-line.md @@ -29,13 +29,17 @@ Usage: spdx-tool [options] [arguments] Options: -h, --help Show this help message and exit -v, --version Show version information and exit + -l, --log Log output to file + -s, --silent Silence console output + --validate Perform self-validation + -r, --result Self-validation result TRX file Commands: help Display extended help about a command add-package Add package to SPDX document (workflow only). add-relationship Add relationship between elements. copy-package Copy package between SPDX documents (workflow only). - diagram Generate mermaid diagram. + diagram [tools] Generate mermaid diagram. find-package Find package ID in SPDX document get-version Get the version of an SPDX package. hash Generate or verify hashes of files diff --git a/docs/spdx-tool-github-ci.md b/docs/spdx-tool-github-ci.md index 8ad8610..ebaa8ac 100644 --- a/docs/spdx-tool-github-ci.md +++ b/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 diff --git a/src/DemaConsulting.SpdxTool/SelfValidation/ValidateDiagram.cs b/src/DemaConsulting.SpdxTool/SelfValidation/ValidateDiagram.cs index 664f5a9..73ca3c6 100644 --- a/src/DemaConsulting.SpdxTool/SelfValidation/ValidateDiagram.cs +++ b/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 diff --git a/src/DemaConsulting.SpdxTool/SelfValidation/ValidateHash.cs b/src/DemaConsulting.SpdxTool/SelfValidation/ValidateHash.cs index 612a642..a50b3e7 100644 --- a/src/DemaConsulting.SpdxTool/SelfValidation/ValidateHash.cs +++ b/src/DemaConsulting.SpdxTool/SelfValidation/ValidateHash.cs @@ -39,7 +39,7 @@ public static void Run(Context context, TestResults.TestResults results) // Report validation result to console context.WriteLine($"- SpdxTool_Hash: {(passed ? "Passed" : "Failed")}"); - + // Add validation result to test results collection results.Results.Add( new TestResult @@ -107,7 +107,7 @@ private static bool DoValidateGenerate() // 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"; } diff --git a/src/DemaConsulting.SpdxTool/SelfValidation/ValidateToMarkdown.cs b/src/DemaConsulting.SpdxTool/SelfValidation/ValidateToMarkdown.cs index 1566f07..87898d8 100644 --- a/src/DemaConsulting.SpdxTool/SelfValidation/ValidateToMarkdown.cs +++ b/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 diff --git a/test/DemaConsulting.SpdxTool.Tests/DemaConsulting.SpdxTool.Tests.csproj b/test/DemaConsulting.SpdxTool.Tests/DemaConsulting.SpdxTool.Tests.csproj index f52b881..d7dc2ac 100644 --- a/test/DemaConsulting.SpdxTool.Tests/DemaConsulting.SpdxTool.Tests.csproj +++ b/test/DemaConsulting.SpdxTool.Tests/DemaConsulting.SpdxTool.Tests.csproj @@ -1,6 +1,7 @@ + net8.0;net9.0;net10.0 12 enable @@ -9,15 +10,16 @@ false true + true true - true true true latest + all @@ -26,6 +28,10 @@ + + + + all runtime; build; native; contentfiles; analyzers; buildtransitive @@ -36,6 +42,7 @@ + true