From a5d4e0a5b0cf2a536f0c1ded2ad7e345dffc0de0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 2 Apr 2026 15:27:54 +0000 Subject: [PATCH 1/8] Add design docs, split requirements into subsystem files, update reviewmark config Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .cspell.yaml | 1 + .reviewmark.yaml | 42 ++- docs/design/introduction.md | 109 ++++++ docs/design/io/io.md | 53 +++ docs/design/system.md | 70 ++++ docs/design/transform/transform.md | 36 ++ docs/reqstream/io/io.yaml | 43 +++ docs/reqstream/ots/ots.yaml | 88 +++++ docs/reqstream/platform-requirements.yaml | 68 ++++ docs/reqstream/system.yaml | 229 ++++++++++++ docs/reqstream/transform/transform.yaml | 20 + requirements.yaml | 429 +--------------------- 12 files changed, 767 insertions(+), 421 deletions(-) create mode 100644 docs/design/introduction.md create mode 100644 docs/design/io/io.md create mode 100644 docs/design/system.md create mode 100644 docs/design/transform/transform.md create mode 100644 docs/reqstream/io/io.yaml create mode 100644 docs/reqstream/ots/ots.yaml create mode 100644 docs/reqstream/platform-requirements.yaml create mode 100644 docs/reqstream/system.yaml create mode 100644 docs/reqstream/transform/transform.yaml diff --git a/.cspell.yaml b/.cspell.yaml index 6708ed2..c9e5119 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -59,6 +59,7 @@ words: - mstest - myterm - nameof + - netstandard - ncipollo - Neko - NOASSERTION diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 31bb85a..06ced4d 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -6,6 +6,9 @@ # Patterns identifying all files that require review. # Processed in order; prefix a pattern with '!' to exclude. needs-review: + - "requirements.yaml" # Root requirements file + - "docs/reqstream/**/*.yaml" # Requirements files + - "docs/design/**/*.md" # Design documentation - "**/*.cs" # All C# source and test files - "!**/obj/**" # Exclude build output - "!**/bin/**" # Exclude build output @@ -21,4 +24,41 @@ evidence-source: # Review sets grouping files by logical unit of review. # Each review-set groups requirements, source, and tests for a coherent software unit # so that an AI-assisted review can verify consistency across the full evidence chain. -reviews: [] +reviews: + - id: SpdxModel-System + title: SpdxModel System Review + paths: + - "docs/reqstream/system.yaml" + - "docs/design/introduction.md" + - "docs/design/system.md" + + - id: SpdxModel-Design + title: SpdxModel Design Review + paths: + - "docs/reqstream/system.yaml" + - "docs/reqstream/platform-requirements.yaml" + - "docs/design/**/*.md" + + - id: SpdxModel-AllRequirements + title: SpdxModel All Requirements Review + paths: + - "requirements.yaml" + - "docs/reqstream/**/*.yaml" + + - id: SpdxModel-IO + title: SpdxModel IO Subsystem Review + paths: + - "docs/reqstream/io/io.yaml" + - "docs/design/io/io.md" + - "src/DemaConsulting.SpdxModel/IO/Spdx2JsonDeserializer.cs" + - "src/DemaConsulting.SpdxModel/IO/Spdx2JsonSerializer.cs" + - "src/DemaConsulting.SpdxModel/IO/SpdxConstants.cs" + - "test/DemaConsulting.SpdxModel.Tests/IO/**/*.cs" + + - id: SpdxModel-Transform + title: SpdxModel Transform Subsystem Review + paths: + - "docs/reqstream/transform/transform.yaml" + - "docs/design/transform/transform.md" + - "src/DemaConsulting.SpdxModel/Transform/SpdxRelationships.cs" + - "test/DemaConsulting.SpdxModel.Tests/Transforms/SpdxRelationshipsTests.cs" diff --git a/docs/design/introduction.md b/docs/design/introduction.md new file mode 100644 index 0000000..f1890b1 --- /dev/null +++ b/docs/design/introduction.md @@ -0,0 +1,109 @@ +# DemaConsulting.SpdxModel Design Documentation + +## Purpose + +This document provides the design overview for the DemaConsulting.SpdxModel library, a .NET library +for reading, writing, and manipulating SPDX (Software Package Data Exchange) documents. It serves as +the entry point for the design documentation, providing architectural context for formal code review, +compliance auditing, and maintenance support. + +## Scope + +This design documentation covers the DemaConsulting.SpdxModel library, including: + +- The SPDX data model (documents, packages, files, snippets, relationships, annotations, checksums, etc.) +- JSON serialization and deserialization (SPDX 2.2 and SPDX 2.3) +- Relationship manipulation utilities + +Excluded from scope: + +- Consumer application code using this library +- CI/CD pipeline configuration +- NuGet package distribution infrastructure + +## Software Structure + +```text +DemaConsulting.SpdxModel (System) +├── IO (Subsystem) +│ ├── Spdx2JsonDeserializer (Unit) +│ ├── Spdx2JsonSerializer (Unit) +│ └── SpdxConstants (Unit) +├── Transform (Subsystem) +│ └── SpdxRelationships (Unit) +├── SpdxAnnotation (Unit) +├── SpdxChecksum (Unit) +├── SpdxCreationInformation (Unit) +├── SpdxDocument (Unit) +├── SpdxElement (Unit) +├── SpdxExternalDocumentReference (Unit) +├── SpdxExternalReference (Unit) +├── SpdxExtractedLicensingInfo (Unit) +├── SpdxFile (Unit) +├── SpdxHelpers (Unit) +├── SpdxLicenseElement (Unit) +├── SpdxPackage (Unit) +├── SpdxPackageVerificationCode (Unit) +├── SpdxRelationship (Unit) +└── SpdxSnippet (Unit) +``` + +OTS Software Items: + +- MSTest — unit test framework +- ReqStream — requirements traceability enforcement +- BuildMark — build notes documentation generation +- VersionMark — tool version documentation +- SarifMark — CodeQL SARIF report generation +- SonarMark — SonarCloud quality report generation + +## Folder Layout + +```text +src/DemaConsulting.SpdxModel/ +├── IO/ +│ ├── Spdx2JsonDeserializer.cs — SPDX 2.x JSON deserialization +│ ├── Spdx2JsonSerializer.cs — SPDX 2.x JSON serialization +│ └── SpdxConstants.cs — SPDX constants +├── Transform/ +│ └── SpdxRelationships.cs — Relationship manipulation utilities +├── SpdxAnnotation.cs — Annotation data model +├── SpdxAnnotationType.cs — Annotation type enum +├── SpdxChecksum.cs — Checksum data model +├── SpdxChecksumAlgorithm.cs — Checksum algorithm enum +├── SpdxCreationInformation.cs — Creation information data model +├── SpdxDocument.cs — Document data model +├── SpdxElement.cs — Base element class +├── SpdxExternalDocumentReference.cs — External document reference model +├── SpdxExternalReference.cs — External reference data model +├── SpdxExtractedLicensingInfo.cs — Extracted licensing info model +├── SpdxFile.cs — File data model +├── SpdxFileType.cs — File type enum +├── SpdxHelpers.cs — Helper utilities +├── SpdxLicenseElement.cs — License element base class +├── SpdxPackage.cs — Package data model +├── SpdxPackageVerificationCode.cs — Package verification code model +├── SpdxReferenceCategory.cs — Reference category enum +├── SpdxRelationship.cs — Relationship data model +├── SpdxRelationshipType.cs — Relationship type enum +└── SpdxSnippet.cs — Snippet data model + +test/DemaConsulting.SpdxModel.Tests/ +├── IO/ +│ ├── Examples/ — Test example JSON files +│ └── (Spdx2JsonDeserialize*.cs and Spdx2JsonSerialize*.cs test files) +├── Transforms/ +│ └── SpdxRelationshipsTests.cs — Relationship utility tests +├── SpdxAnnotationTests.cs +├── SpdxChecksumTests.cs +├── SpdxCreationInformationTests.cs +├── SpdxDocumentTests.cs +├── SpdxExternalDocumentReferenceTests.cs +├── SpdxExternalReferenceTests.cs +├── SpdxExtractedLicensingInfoTests.cs +├── SpdxFileTests.cs +├── SpdxPackageTests.cs +├── SpdxPackageVerificationCodeTests.cs +├── SpdxRelationshipTests.cs +└── SpdxSnippetTests.cs +``` diff --git a/docs/design/io/io.md b/docs/design/io/io.md new file mode 100644 index 0000000..9a9a8b2 --- /dev/null +++ b/docs/design/io/io.md @@ -0,0 +1,53 @@ +# IO Subsystem Design + +## Purpose + +The IO subsystem provides JSON serialization and deserialization for SPDX 2.x documents, +converting between the in-memory `SpdxDocument` object model and SPDX JSON files conforming +to the SPDX 2.2 and 2.3 specifications. + +## Units + +| Unit | File | Responsibility | +| ---- | ---- | -------------- | +| `Spdx2JsonDeserializer` | `IO/Spdx2JsonDeserializer.cs` | Reads SPDX 2.x JSON into the object model | +| `Spdx2JsonSerializer` | `IO/Spdx2JsonSerializer.cs` | Writes the object model to SPDX 2.x JSON | +| `SpdxConstants` | `IO/SpdxConstants.cs` | String constants for SPDX JSON field names | + +## Design + +### Spdx2JsonDeserializer + +`Spdx2JsonDeserializer` reads a JSON stream or string and populates a `SpdxDocument`. It uses +`System.Text.Json` `JsonDocument` for DOM-based parsing, navigating named properties to +reconstruct each element. Both SPDX 2.2 and 2.3 JSON schemas are supported; version differences +are handled transparently during parsing. + +Key design decisions: + +- DOM-based parsing (rather than streaming) to allow forward references between document elements +- Graceful handling of optional SPDX fields (missing fields result in default values) + +### Spdx2JsonSerializer + +`Spdx2JsonSerializer` takes an `SpdxDocument` and writes it to a `Utf8JsonWriter`. It iterates +over each element collection in document order, writing the appropriate JSON structure for each +SPDX element type. + +Key design decisions: + +- Output follows SPDX 2.3 JSON schema by default +- Optional fields are omitted when empty or null to keep output clean + +### SpdxConstants + +`SpdxConstants` is a static class holding string constants for every JSON property name used in +the SPDX 2.x JSON format. Using named constants prevents typos and centralizes the mapping +between the object model and the serialized form. + +## Dependencies + +The IO subsystem depends on: + +- `System.Text.Json` (BCL / NuGet) +- All data model units in the root namespace (`SpdxDocument`, `SpdxPackage`, etc.) diff --git a/docs/design/system.md b/docs/design/system.md new file mode 100644 index 0000000..1e05f3e --- /dev/null +++ b/docs/design/system.md @@ -0,0 +1,70 @@ +# DemaConsulting.SpdxModel System Design + +## System Architecture + +DemaConsulting.SpdxModel is a .NET library providing a complete implementation of the SPDX +(Software Package Data Exchange) data model. The library exposes an in-memory object model +representing all SPDX document elements, plus serialization and transformation capabilities. + +### Major Components + +- **Data Model** — C# classes representing every SPDX 2.x element (documents, packages, files, + snippets, relationships, annotations, checksums, external references, etc.) +- **IO Subsystem** — JSON serialization and deserialization for SPDX 2.2 and 2.3 formats using + `System.Text.Json` +- **Transform Subsystem** — Utilities for manipulating SPDX documents, starting with relationship + management + +## External Interfaces and Dependencies + +### External Dependencies + +- **System.Text.Json** — used by the IO subsystem for JSON reading and writing; available as part of + the .NET BCL from .NET 6 onwards and via NuGet for .NET Standard 2.0 +- **.NET Standard 2.0 / .NET 8 / .NET 9 / .NET 10** — target frameworks + +### Public API Surface + +The library exposes: + +- `SpdxDocument` — root object representing a complete SPDX document +- Data model classes for all SPDX elements +- `Spdx2JsonDeserializer` — reads SPDX JSON into the object model +- `Spdx2JsonSerializer` — writes the object model to SPDX JSON +- `SpdxRelationships` — static utilities for relationship manipulation + +## Data Flow + +```text +JSON File + │ + ▼ +Spdx2JsonDeserializer ──► SpdxDocument (in-memory model) + │ + (manipulate via + Transform utilities) + │ + ▼ + Spdx2JsonSerializer ──► JSON File +``` + +## System-Wide Design Constraints and Decisions + +- **Immutability by convention**: data model classes use public mutable properties to allow + flexible construction while deep-copy methods provide safe cloning +- **Nullable reference types enabled**: all public API members declare nullability explicitly +- **No external runtime dependencies beyond BCL**: keeps the library lightweight and avoids + dependency conflicts for consumers +- **Target multi-framework**: the library targets `netstandard2.0`, `net8.0`, `net9.0`, + and `net10.0` simultaneously + +## Integration Patterns + +Consumers typically: + +1. Deserialize an SPDX document from a JSON file using `Spdx2JsonDeserializer` +2. Inspect or modify the `SpdxDocument` object model in memory +3. Serialize back to JSON using `Spdx2JsonSerializer` + +For programmatic SBOM construction, consumers create `SpdxDocument` instances directly and +populate the data model before serializing. diff --git a/docs/design/transform/transform.md b/docs/design/transform/transform.md new file mode 100644 index 0000000..d5c1d98 --- /dev/null +++ b/docs/design/transform/transform.md @@ -0,0 +1,36 @@ +# Transform Subsystem Design + +## Purpose + +The Transform subsystem provides utilities for manipulating SPDX documents in memory, enabling +consumers to programmatically build and modify SPDX relationship graphs. + +## Units + +| Unit | File | Responsibility | +| ---- | ---- | -------------- | +| `SpdxRelationships` | `Transform/SpdxRelationships.cs` | Utilities for adding and managing SPDX relationships | + +## Design + +### SpdxRelationships + +`SpdxRelationships` is a static utility class that provides helper methods for adding relationships +to an `SpdxDocument`. It ensures relationships are added without duplication and in a consistent +manner, reducing boilerplate for consumers constructing SPDX documents programmatically. + +Key methods: + +- `AddRelationship` — adds a single relationship to the document if it does not already exist +- `AddRelationships` — adds multiple relationships, deduplicating against existing entries + +Key design decisions: + +- Static class with no instance state to simplify usage +- Deduplication logic prevents malformed documents with duplicate relationship entries + +## Dependencies + +The Transform subsystem depends on: + +- `SpdxDocument` and `SpdxRelationship` data model units diff --git a/docs/reqstream/io/io.yaml b/docs/reqstream/io/io.yaml new file mode 100644 index 0000000..20231bf --- /dev/null +++ b/docs/reqstream/io/io.yaml @@ -0,0 +1,43 @@ +--- +# SpdxModel IO Subsystem Requirements +# +# This file defines the serialization requirements for the IO subsystem +# of the SpdxModel library. + +sections: + - title: IO Subsystem Requirements + sections: + - title: Serialization + requirements: + - id: SpdxModel-Ser-Deserialize22Json + title: The library shall support deserializing SPDX 2.2 JSON documents. + tags: + - serialization + justification: | + Deserializing SPDX 2.2 JSON documents is essential for backward compatibility and + interoperability with systems using the SPDX 2.2 specification. This ensures that the + library can read and process existing SPDX 2.2 documents from various sources. + tests: + - Spdx2JsonDeserializer_Deserialize_ValidSpdx22JsonReturnsExpectedDocument + + - id: SpdxModel-Ser-Deserialize23Json + title: The library shall support deserializing SPDX 2.3 JSON documents. + tags: + - serialization + justification: | + Support for SPDX 2.3 JSON documents ensures the library remains current with the latest + SPDX specification. This allows users to leverage new features and improvements introduced + in SPDX 2.3 while maintaining compatibility with modern SBOM tools. + tests: + - Spdx2JsonDeserializer_Deserialize_ValidSpdx23JsonReturnsExpectedDocument + + - id: SpdxModel-Ser-SerializeJson + title: The library shall support serializing SPDX documents to JSON format. + tags: + - serialization + justification: | + Serialization capability is fundamental for creating and exporting SPDX documents in JSON + format. This enables users to generate SBOMs programmatically and share them with other + systems and tools in the SPDX ecosystem. + tests: + - Spdx2JsonSerializer_SerializeDocument_CorrectResults diff --git a/docs/reqstream/ots/ots.yaml b/docs/reqstream/ots/ots.yaml new file mode 100644 index 0000000..03a8c40 --- /dev/null +++ b/docs/reqstream/ots/ots.yaml @@ -0,0 +1,88 @@ +--- +# SpdxModel OTS Software Requirements +# +# This file defines the requirements for OTS (Off-The-Shelf) software items +# used by the SpdxModel library. + +sections: + - title: OTS Software + requirements: + - id: SpdxModel-OTS-MSTest + title: MSTest shall execute unit tests and report results. + tags: + - ots + justification: | + MSTest (MSTest.TestFramework and MSTest.TestAdapter) is the unit-testing framework used + by the project. It discovers and runs all test methods and writes TRX result files that + feed into coverage reporting and requirements traceability. Passing tests confirm the + framework is functioning correctly. + tests: + - Spdx2JsonDeserializer_Deserialize_ValidSpdx22JsonReturnsExpectedDocument + - Spdx2JsonDeserializer_Deserialize_ValidSpdx23JsonReturnsExpectedDocument + - Spdx2JsonSerializer_SerializeDocument_CorrectResults + + - id: SpdxModel-OTS-ReqStream + title: ReqStream shall enforce that every requirement is linked to passing test evidence. + tags: + - ots + justification: | + DemaConsulting.ReqStream processes requirements.yaml and the TRX test-result files to + produce a requirements report, justifications document, and traceability matrix. When + run with --enforce, it exits with a non-zero code if any requirement lacks test evidence, + making unproven requirements a build-breaking condition. A successful pipeline run with + --enforce proves all requirements are covered and that ReqStream is functioning. + tests: + - ReqStream_EnforcementMode + + - id: SpdxModel-OTS-BuildMark + title: BuildMark shall generate build-notes documentation from GitHub Actions metadata. + tags: + - ots + justification: | + DemaConsulting.BuildMark queries the GitHub API to capture workflow run details and + renders them as a markdown build-notes document included in the release artifacts. + It runs as part of the same CI pipeline that produces the TRX test results, so a + successful pipeline run is evidence that BuildMark executed without error. + tests: + - BuildMark_MarkdownReportGeneration + + - id: SpdxModel-OTS-VersionMark + title: VersionMark shall publish captured tool-version information. + tags: + - ots + justification: | + DemaConsulting.VersionMark reads version metadata for each dotnet tool used in the + pipeline and writes a versions markdown document included in the release artifacts. + It runs in the same CI pipeline that produces the TRX test results, so a successful + pipeline run is evidence that VersionMark executed without error. + tests: + - VersionMark_CapturesVersions + - VersionMark_GeneratesMarkdownReport + + - id: SpdxModel-OTS-SarifMark + title: SarifMark shall convert CodeQL SARIF results into a markdown report. + tags: + - ots + justification: | + DemaConsulting.SarifMark reads the SARIF output produced by CodeQL code scanning and + renders it as a human-readable markdown document included in the release artifacts. + It runs in the same CI pipeline that produces the TRX test results, so a successful + pipeline run is evidence that SarifMark executed without error. + tests: + - SarifMark_SarifReading + - SarifMark_MarkdownReportGeneration + + - id: SpdxModel-OTS-SonarMark + title: SonarMark shall generate a SonarCloud quality report. + tags: + - ots + justification: | + DemaConsulting.SonarMark retrieves quality-gate and metrics data from SonarCloud and + renders it as a markdown document included in the release artifacts. It runs in the + same CI pipeline that produces the TRX test results, so a successful pipeline run is + evidence that SonarMark executed without error. + tests: + - SonarMark_QualityGateRetrieval + - SonarMark_IssuesRetrieval + - SonarMark_HotSpotsRetrieval + - SonarMark_MarkdownReportGeneration diff --git a/docs/reqstream/platform-requirements.yaml b/docs/reqstream/platform-requirements.yaml new file mode 100644 index 0000000..2dddb52 --- /dev/null +++ b/docs/reqstream/platform-requirements.yaml @@ -0,0 +1,68 @@ +--- +# SpdxModel Platform Requirements +# +# This file defines the platform support requirements for the SpdxModel library. + +sections: + - title: Platform Requirements + requirements: + - id: SpdxModel-Plt-MacOS + title: The library shall build and run on macOS platforms. + tags: + - platform + justification: | + DEMA Consulting libraries must support macOS for developers using Apple platforms. + tests: + # Tests link to "macos" to ensure results come from macOS platform + - "macos@Spdx2JsonDeserializer_Deserialize_ValidSpdx22JsonReturnsExpectedDocument" + + - id: SpdxModel-Plt-Net8 + title: The library shall support .NET 8 runtime. + tags: + - platform + justification: | + .NET 8 is a long-term support (LTS) release and provides a stable foundation for + enterprise applications. Supporting .NET 8 ensures the library can be used in production + environments requiring long-term stability and support. + tests: + - net8.0@Spdx2JsonDeserializer_Deserialize_ValidSpdx22JsonReturnsExpectedDocument + - net8.0@Spdx2JsonSerializer_SerializeDocument_CorrectResults + + - id: SpdxModel-Plt-Net9 + title: The library shall support .NET 9 runtime. + tags: + - platform + justification: | + .NET 9 is a standard-term support (STS) release providing newer features and performance + improvements. Supporting .NET 9 allows users to leverage the latest .NET capabilities while + the framework is current. + tests: + - net9.0@Spdx2JsonDeserializer_Deserialize_ValidSpdx22JsonReturnsExpectedDocument + - net9.0@Spdx2JsonSerializer_SerializeDocument_CorrectResults + + - id: SpdxModel-Plt-Net10 + title: The library shall support .NET 10 runtime. + tags: + - platform + justification: | + .NET 10 represents the latest .NET platform release. Supporting .NET 10 ensures users + can adopt the most recent framework version and benefit from the latest performance, + security, and feature improvements. + tests: + - net10.0@Spdx2JsonDeserializer_Deserialize_ValidSpdx22JsonReturnsExpectedDocument + - net10.0@Spdx2JsonSerializer_SerializeDocument_CorrectResults + + - id: SpdxModel-Plt-NetStd20 + title: The library shall support the .NET Standard 2.0 target framework. + tags: + - platform + justification: | + .NET Standard 2.0 is a widely-supported target framework that enables the library to + be used in MSBuild extensions and other tooling that requires .NET Standard compatibility. + Supporting this target framework ensures the library can be integrated into a broader + range of .NET projects, including those targeting .NET Framework and older .NET Core versions. + The net481 test target on Windows provides direct runtime evidence of .NET Standard 2.0 + compatibility, as .NET Framework 4.8.1 fully implements the .NET Standard 2.0 API surface. + tests: + - "net481@Spdx2JsonDeserializer_Deserialize_ValidSpdx22JsonReturnsExpectedDocument" + - "net481@Spdx2JsonSerializer_SerializeDocument_CorrectResults" diff --git a/docs/reqstream/system.yaml b/docs/reqstream/system.yaml new file mode 100644 index 0000000..e78570e --- /dev/null +++ b/docs/reqstream/system.yaml @@ -0,0 +1,229 @@ +--- +# SpdxModel System Requirements +# +# This file defines the system-level data model and validation requirements +# for the SpdxModel library. + +sections: + - title: SpdxModel Library Requirements + sections: + - title: Data Model + requirements: + - id: SpdxModel-Data-CreationInformation + title: The library shall support SPDX document creation information. + tags: + - data-model + justification: | + Creation information is a required element of SPDX documents that provides metadata about + who created the document and when. Supporting this element is essential for SPDX compliance + and traceability of document provenance. + tests: + - SpdxCreationInformation_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeCreationInformation_CorrectResults + - Spdx2JsonSerializer_SerializeCreationInformation_CorrectResults + + - id: SpdxModel-Data-Packages + title: The library shall support SPDX packages. + tags: + - data-model + justification: | + Packages are core elements in SPDX documents representing software packages in an SBOM. + Supporting package elements is fundamental to the library's purpose of managing software + bill of materials and dependency information. + tests: + - SpdxPackage_SameComparer_ComparesCorrectly + - SpdxPackage_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializePackage_CorrectResults + - Spdx2JsonSerializer_SerializePackage_CorrectResults + + - id: SpdxModel-Data-Files + title: The library shall support SPDX files. + tags: + - data-model + justification: | + Files are essential components in SPDX documents for detailed SBOM creation. Supporting + file elements enables fine-grained tracking of individual source files, binaries, and + their associated licensing and copyright information. + tests: + - SpdxFile_SameComparer_ComparesCorrectly + - SpdxFile_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeFile_CorrectResults + - Spdx2JsonSerializer_SerializeFile_CorrectResults + + - id: SpdxModel-Data-Snippets + title: The library shall support SPDX snippets. + tags: + - data-model + justification: | + Snippets represent portions of files and are important for documenting code reuse at a + granular level. This supports compliance scenarios where specific code segments have + different licensing or provenance than their containing files. + tests: + - SpdxSnippet_SameComparer_ComparesCorrectly + - SpdxSnippet_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeSnippet_CorrectResults + - Spdx2JsonSerializer_SerializeSnippet_CorrectResults + + - id: SpdxModel-Data-Relationships + title: The library shall support SPDX relationships. + tags: + - data-model + justification: | + Relationships define connections between SPDX elements and are critical for expressing + dependency graphs, containment hierarchies, and other associations in SBOMs. This is + fundamental to representing complex software structures. + tests: + - SpdxRelationship_SameComparer_ComparesCorrectly + - SpdxRelationship_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeRelationship_CorrectResults + - Spdx2JsonSerializer_SerializeRelationship_CorrectResults + + - id: SpdxModel-Data-Annotations + title: The library shall support SPDX annotations. + tags: + - data-model + justification: | + Annotations allow adding review and assessment information to SPDX elements. This supports + compliance workflows where reviewers need to document their findings and decisions about + software components. + tests: + - SpdxAnnotation_SameComparer_ComparesCorrectly + - SpdxAnnotation_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeAnnotation_CorrectResults + - Spdx2JsonSerializer_SerializeAnnotation_CorrectResults + + - id: SpdxModel-Data-Checksums + title: The library shall support SPDX checksums with multiple algorithms. + tags: + - data-model + justification: | + Checksums with multiple algorithms provide integrity verification for files and packages. + Supporting multiple algorithms ensures flexibility and compatibility with different security + requirements and organizational policies. + tests: + - SpdxChecksum_SameComparer_ComparesCorrectly + - SpdxChecksum_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeChecksum_CorrectResults + - Spdx2JsonSerializer_SerializeChecksum_CorrectResults + + - id: SpdxModel-Data-ExternalReferences + title: The library shall support SPDX external references. + tags: + - data-model + justification: | + External references enable linking SPDX elements to external resources like package + registries, vulnerability databases, and documentation. This enriches SBOMs with contextual + information from authoritative sources. + tests: + - SpdxExternalReference_SameComparer_ComparesCorrectly + - SpdxExternalReference_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeExternalReference_CorrectResults + - Spdx2JsonSerializer_SerializeExternalReference_CorrectResults + + - id: SpdxModel-Data-ExternalDocumentReferences + title: The library shall support SPDX external document references. + tags: + - data-model + justification: | + External document references allow SPDX documents to reference other SPDX documents, + enabling modular SBOM construction and linking between related software inventories. This + is essential for managing complex multi-component software systems. + tests: + - SpdxExternalDocumentReference_SameComparer_ComparesCorrectly + - SpdxExternalDocumentReference_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeExternalDocumentReference_CorrectResults + - Spdx2JsonSerializer_SerializeExternalDocumentReference_CorrectResults + + - id: SpdxModel-Data-ExtractedLicensingInfo + title: The library shall support SPDX extracted licensing information. + tags: + - data-model + justification: | + Extracted licensing information supports documenting non-standard licenses found in + software packages. This is critical for compliance when software contains licenses not + in the SPDX license list. + tests: + - SpdxExtractedLicensingInfo_SameComparer_ComparesCorrectly + - SpdxExtractedLicensingInfo_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeExtractedLicensingInfo_CorrectResults + - Spdx2JsonSerializer_SerializeExtractedLicensingInfo_CorrectResults + + - id: SpdxModel-Data-PackageVerificationCodes + title: The library shall support SPDX package verification codes. + tags: + - data-model + justification: | + Package verification codes provide a way to verify package contents integrity. This + cryptographic verification mechanism is important for ensuring that package contents + have not been tampered with or corrupted. + tests: + - SpdxPackageVerificationCode_SameComparer_ComparesCorrectly + - SpdxPackageVerificationCode_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializePackageVerificationCode_CorrectResults + - Spdx2JsonSerializer_SerializePackageVerificationCode_CorrectResults + + - id: SpdxModel-Data-RootPackages + title: The library shall support retrieving root packages from an SPDX document. + tags: + - data-model + justification: | + Retrieving root packages helps identify top-level components in an SBOM. This is essential + for understanding the primary software packages in a document and navigating the dependency + graph from its entry points. + tests: + - SpdxDocument_GetRootPackages_CorrectPackages + + - id: SpdxModel-Data-DeepCopy + title: The library shall support deep copying of SPDX elements. + tags: + - data-model + justification: | + Deep copying enables creating independent copies of SPDX elements for modification without + affecting the original. This is crucial for SBOM manipulation scenarios like merging, + filtering, or transforming documents. + tests: + - SpdxDocument_DeepCopy_CreatesEqualButDistinctInstance + - SpdxPackage_DeepCopy_CreatesEqualButDistinctInstance + - SpdxFile_DeepCopy_CreatesEqualButDistinctInstance + + - id: SpdxModel-Data-NullableReferenceTypes + title: The library shall provide type-safe APIs with nullable reference types. + tags: + - data-model + justification: | + Nullable reference types enhance type safety by making nullability explicit in the type + system. This improves code quality, reduces null reference exceptions, and makes the API + more intuitive for consumers. + tests: + - SpdxDocument_DeepCopy_CreatesEqualButDistinctInstance + - SpdxPackage_DeepCopy_CreatesEqualButDistinctInstance + + - id: SpdxModel-Data-ComparisonUtilities + title: The library shall provide comparison utilities for SPDX elements. + tags: + - data-model + justification: | + Comparison utilities enable applications to determine equality and equivalence between + SPDX elements. This is essential for testing, change detection, and implementing operations + like document merging or deduplication. + tests: + - SpdxDocument_SameComparer_ComparesCorrectly + - SpdxPackage_SameComparer_ComparesCorrectly + - SpdxFile_SameComparer_ComparesCorrectly + - SpdxRelationship_SameComparer_ComparesCorrectly + + - title: Validation + requirements: + - id: SpdxModel-Val-ElementValidation + title: The library shall support validation of SPDX elements. + tags: + - validation + justification: | + Validation ensures SPDX documents and elements conform to the specification requirements. + This helps users catch errors early and produce compliant SBOMs that will be accepted by + other tools in the SPDX ecosystem. + tests: + - SpdxDocument_Validate_NoIssues + - SpdxAnnotation_Validate_InvalidAnnotator + - SpdxChecksum_Validate_InvalidAlgorithm + - SpdxCreationInformation_Validate_MissingCreators diff --git a/docs/reqstream/transform/transform.yaml b/docs/reqstream/transform/transform.yaml new file mode 100644 index 0000000..a6e59ed --- /dev/null +++ b/docs/reqstream/transform/transform.yaml @@ -0,0 +1,20 @@ +--- +# SpdxModel Transform Subsystem Requirements +# +# This file defines the requirements for the Transform subsystem +# of the SpdxModel library. + +sections: + - title: Transform Subsystem Requirements + requirements: + - id: SpdxModel-Data-RelationshipUtilities + title: The library shall provide utilities for manipulating SPDX relationships. + tags: + - data-model + justification: | + Relationship manipulation utilities simplify common operations on SPDX documents such as + adding and managing relationships between elements. This improves developer productivity + and reduces errors when constructing complex SBOMs. + tests: + - SpdxRelationships_AddSingle_Success + - SpdxRelationships_AddMultiple_Success diff --git a/requirements.yaml b/requirements.yaml index 6fa3242..30c1f05 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -1,423 +1,12 @@ --- # SpdxModel Library Requirements # -# This file defines the requirements for the SpdxModel library. -# Requirements are verified through tests and documented in the requirements and trace matrix documents. - -sections: - - title: SpdxModel Library Requirements - sections: - - title: Functional Requirements - sections: - - title: Serialization - requirements: - - id: SpdxModel-Ser-Deserialize22Json - title: The library shall support deserializing SPDX 2.2 JSON documents. - tags: - - serialization - justification: | - Deserializing SPDX 2.2 JSON documents is essential for backward compatibility and - interoperability with systems using the SPDX 2.2 specification. This ensures that the - library can read and process existing SPDX 2.2 documents from various sources. - tests: - - Spdx2JsonDeserializer_Deserialize_ValidSpdx22JsonReturnsExpectedDocument - - - id: SpdxModel-Ser-Deserialize23Json - title: The library shall support deserializing SPDX 2.3 JSON documents. - tags: - - serialization - justification: | - Support for SPDX 2.3 JSON documents ensures the library remains current with the latest - SPDX specification. This allows users to leverage new features and improvements introduced - in SPDX 2.3 while maintaining compatibility with modern SBOM tools. - tests: - - Spdx2JsonDeserializer_Deserialize_ValidSpdx23JsonReturnsExpectedDocument - - - id: SpdxModel-Ser-SerializeJson - title: The library shall support serializing SPDX documents to JSON format. - tags: - - serialization - justification: | - Serialization capability is fundamental for creating and exporting SPDX documents in JSON - format. This enables users to generate SBOMs programmatically and share them with other - systems and tools in the SPDX ecosystem. - tests: - - Spdx2JsonSerializer_SerializeDocument_CorrectResults - - - title: Data Model - requirements: - - id: SpdxModel-Data-CreationInformation - title: The library shall support SPDX document creation information. - tags: - - data-model - justification: | - Creation information is a required element of SPDX documents that provides metadata about - who created the document and when. Supporting this element is essential for SPDX compliance - and traceability of document provenance. - tests: - - SpdxCreationInformation_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeCreationInformation_CorrectResults - - Spdx2JsonSerializer_SerializeCreationInformation_CorrectResults - - - id: SpdxModel-Data-Packages - title: The library shall support SPDX packages. - tags: - - data-model - justification: | - Packages are core elements in SPDX documents representing software packages in an SBOM. - Supporting package elements is fundamental to the library's purpose of managing software - bill of materials and dependency information. - tests: - - SpdxPackage_SameComparer_ComparesCorrectly - - SpdxPackage_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializePackage_CorrectResults - - Spdx2JsonSerializer_SerializePackage_CorrectResults - - - id: SpdxModel-Data-Files - title: The library shall support SPDX files. - tags: - - data-model - justification: | - Files are essential components in SPDX documents for detailed SBOM creation. Supporting - file elements enables fine-grained tracking of individual source files, binaries, and - their associated licensing and copyright information. - tests: - - SpdxFile_SameComparer_ComparesCorrectly - - SpdxFile_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeFile_CorrectResults - - Spdx2JsonSerializer_SerializeFile_CorrectResults - - - id: SpdxModel-Data-Snippets - title: The library shall support SPDX snippets. - tags: - - data-model - justification: | - Snippets represent portions of files and are important for documenting code reuse at a - granular level. This supports compliance scenarios where specific code segments have - different licensing or provenance than their containing files. - tests: - - SpdxSnippet_SameComparer_ComparesCorrectly - - SpdxSnippet_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeSnippet_CorrectResults - - Spdx2JsonSerializer_SerializeSnippet_CorrectResults - - - id: SpdxModel-Data-Relationships - title: The library shall support SPDX relationships. - tags: - - data-model - justification: | - Relationships define connections between SPDX elements and are critical for expressing - dependency graphs, containment hierarchies, and other associations in SBOMs. This is - fundamental to representing complex software structures. - tests: - - SpdxRelationship_SameComparer_ComparesCorrectly - - SpdxRelationship_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeRelationship_CorrectResults - - Spdx2JsonSerializer_SerializeRelationship_CorrectResults - - - id: SpdxModel-Data-Annotations - title: The library shall support SPDX annotations. - tags: - - data-model - justification: | - Annotations allow adding review and assessment information to SPDX elements. This supports - compliance workflows where reviewers need to document their findings and decisions about - software components. - tests: - - SpdxAnnotation_SameComparer_ComparesCorrectly - - SpdxAnnotation_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeAnnotation_CorrectResults - - Spdx2JsonSerializer_SerializeAnnotation_CorrectResults - - - id: SpdxModel-Data-Checksums - title: The library shall support SPDX checksums with multiple algorithms. - tags: - - data-model - justification: | - Checksums with multiple algorithms provide integrity verification for files and packages. - Supporting multiple algorithms ensures flexibility and compatibility with different security - requirements and organizational policies. - tests: - - SpdxChecksum_SameComparer_ComparesCorrectly - - SpdxChecksum_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeChecksum_CorrectResults - - Spdx2JsonSerializer_SerializeChecksum_CorrectResults - - - id: SpdxModel-Data-ExternalReferences - title: The library shall support SPDX external references. - tags: - - data-model - justification: | - External references enable linking SPDX elements to external resources like package - registries, vulnerability databases, and documentation. This enriches SBOMs with contextual - information from authoritative sources. - tests: - - SpdxExternalReference_SameComparer_ComparesCorrectly - - SpdxExternalReference_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeExternalReference_CorrectResults - - Spdx2JsonSerializer_SerializeExternalReference_CorrectResults - - - id: SpdxModel-Data-ExternalDocumentReferences - title: The library shall support SPDX external document references. - tags: - - data-model - justification: | - External document references allow SPDX documents to reference other SPDX documents, - enabling modular SBOM construction and linking between related software inventories. This - is essential for managing complex multi-component software systems. - tests: - - SpdxExternalDocumentReference_SameComparer_ComparesCorrectly - - SpdxExternalDocumentReference_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeExternalDocumentReference_CorrectResults - - Spdx2JsonSerializer_SerializeExternalDocumentReference_CorrectResults - - - id: SpdxModel-Data-ExtractedLicensingInfo - title: The library shall support SPDX extracted licensing information. - tags: - - data-model - justification: | - Extracted licensing information supports documenting non-standard licenses found in - software packages. This is critical for compliance when software contains licenses not - in the SPDX license list. - tests: - - SpdxExtractedLicensingInfo_SameComparer_ComparesCorrectly - - SpdxExtractedLicensingInfo_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeExtractedLicensingInfo_CorrectResults - - Spdx2JsonSerializer_SerializeExtractedLicensingInfo_CorrectResults - - - id: SpdxModel-Data-PackageVerificationCodes - title: The library shall support SPDX package verification codes. - tags: - - data-model - justification: | - Package verification codes provide a way to verify package contents integrity. This - cryptographic verification mechanism is important for ensuring that package contents - have not been tampered with or corrupted. - tests: - - SpdxPackageVerificationCode_SameComparer_ComparesCorrectly - - SpdxPackageVerificationCode_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializePackageVerificationCode_CorrectResults - - Spdx2JsonSerializer_SerializePackageVerificationCode_CorrectResults - - - id: SpdxModel-Data-RelationshipUtilities - title: The library shall provide utilities for manipulating SPDX relationships. - tags: - - data-model - justification: | - Relationship manipulation utilities simplify common operations on SPDX documents such as - adding and managing relationships between elements. This improves developer productivity - and reduces errors when constructing complex SBOMs. - tests: - - SpdxRelationships_AddSingle_Success - - SpdxRelationships_AddMultiple_Success - - - id: SpdxModel-Data-RootPackages - title: The library shall support retrieving root packages from an SPDX document. - tags: - - data-model - justification: | - Retrieving root packages helps identify top-level components in an SBOM. This is essential - for understanding the primary software packages in a document and navigating the dependency - graph from its entry points. - tests: - - SpdxDocument_GetRootPackages_CorrectPackages - - - id: SpdxModel-Data-DeepCopy - title: The library shall support deep copying of SPDX elements. - tags: - - data-model - justification: | - Deep copying enables creating independent copies of SPDX elements for modification without - affecting the original. This is crucial for SBOM manipulation scenarios like merging, - filtering, or transforming documents. - tests: - - SpdxDocument_DeepCopy_CreatesEqualButDistinctInstance - - SpdxPackage_DeepCopy_CreatesEqualButDistinctInstance - - SpdxFile_DeepCopy_CreatesEqualButDistinctInstance - - - id: SpdxModel-Data-NullableReferenceTypes - title: The library shall provide type-safe APIs with nullable reference types. - tags: - - data-model - justification: | - Nullable reference types enhance type safety by making nullability explicit in the type - system. This improves code quality, reduces null reference exceptions, and makes the API - more intuitive for consumers. - tests: - - SpdxDocument_DeepCopy_CreatesEqualButDistinctInstance - - SpdxPackage_DeepCopy_CreatesEqualButDistinctInstance - - - id: SpdxModel-Data-ComparisonUtilities - title: The library shall provide comparison utilities for SPDX elements. - tags: - - data-model - justification: | - Comparison utilities enable applications to determine equality and equivalence between - SPDX elements. This is essential for testing, change detection, and implementing operations - like document merging or deduplication. - tests: - - SpdxDocument_SameComparer_ComparesCorrectly - - SpdxPackage_SameComparer_ComparesCorrectly - - SpdxFile_SameComparer_ComparesCorrectly - - SpdxRelationship_SameComparer_ComparesCorrectly - - - title: Validation - requirements: - - id: SpdxModel-Val-ElementValidation - title: The library shall support validation of SPDX elements. - tags: - - validation - justification: | - Validation ensures SPDX documents and elements conform to the specification requirements. - This helps users catch errors early and produce compliant SBOMs that will be accepted by - other tools in the SPDX ecosystem. - tests: - - SpdxDocument_Validate_NoIssues - - SpdxAnnotation_Validate_InvalidAnnotator - - SpdxChecksum_Validate_InvalidAlgorithm - - SpdxCreationInformation_Validate_MissingCreators - - - title: Platform Requirements - requirements: - - id: SpdxModel-Plt-MacOS - title: The library shall build and run on macOS platforms. - tags: - - platform - justification: | - DEMA Consulting libraries must support macOS for developers using Apple platforms. - tests: - # Tests link to "macos" to ensure results come from macOS platform - - "macos@Spdx2JsonDeserializer_Deserialize_ValidSpdx22JsonReturnsExpectedDocument" - - - id: SpdxModel-Plt-Net8 - title: The library shall support .NET 8 runtime. - tags: - - platform - justification: | - .NET 8 is a long-term support (LTS) release and provides a stable foundation for - enterprise applications. Supporting .NET 8 ensures the library can be used in production - environments requiring long-term stability and support. - tests: - - net8.0@Spdx2JsonDeserializer_Deserialize_ValidSpdx22JsonReturnsExpectedDocument - - net8.0@Spdx2JsonSerializer_SerializeDocument_CorrectResults - - - id: SpdxModel-Plt-Net9 - title: The library shall support .NET 9 runtime. - tags: - - platform - justification: | - .NET 9 is a standard-term support (STS) release providing newer features and performance - improvements. Supporting .NET 9 allows users to leverage the latest .NET capabilities while - the framework is current. - tests: - - net9.0@Spdx2JsonDeserializer_Deserialize_ValidSpdx22JsonReturnsExpectedDocument - - net9.0@Spdx2JsonSerializer_SerializeDocument_CorrectResults - - - id: SpdxModel-Plt-Net10 - title: The library shall support .NET 10 runtime. - tags: - - platform - justification: | - .NET 10 represents the latest .NET platform release. Supporting .NET 10 ensures users - can adopt the most recent framework version and benefit from the latest performance, - security, and feature improvements. - tests: - - net10.0@Spdx2JsonDeserializer_Deserialize_ValidSpdx22JsonReturnsExpectedDocument - - net10.0@Spdx2JsonSerializer_SerializeDocument_CorrectResults - - - id: SpdxModel-Plt-NetStd20 - title: The library shall support the .NET Standard 2.0 target framework. - tags: - - platform - justification: | - .NET Standard 2.0 is a widely-supported target framework that enables the library to - be used in MSBuild extensions and other tooling that requires .NET Standard compatibility. - Supporting this target framework ensures the library can be integrated into a broader - range of .NET projects, including those targeting .NET Framework and older .NET Core versions. - The net481 test target on Windows provides direct runtime evidence of .NET Standard 2.0 - compatibility, as .NET Framework 4.8.1 fully implements the .NET Standard 2.0 API surface. - tests: - - "net481@Spdx2JsonDeserializer_Deserialize_ValidSpdx22JsonReturnsExpectedDocument" - - "net481@Spdx2JsonSerializer_SerializeDocument_CorrectResults" - - - title: OTS Software - requirements: - - id: SpdxModel-OTS-MSTest - title: MSTest shall execute unit tests and report results. - tags: - - ots - justification: | - MSTest (MSTest.TestFramework and MSTest.TestAdapter) is the unit-testing framework used - by the project. It discovers and runs all test methods and writes TRX result files that - feed into coverage reporting and requirements traceability. Passing tests confirm the - framework is functioning correctly. - tests: - - Spdx2JsonDeserializer_Deserialize_ValidSpdx22JsonReturnsExpectedDocument - - Spdx2JsonDeserializer_Deserialize_ValidSpdx23JsonReturnsExpectedDocument - - Spdx2JsonSerializer_SerializeDocument_CorrectResults - - - id: SpdxModel-OTS-ReqStream - title: ReqStream shall enforce that every requirement is linked to passing test evidence. - tags: - - ots - justification: | - DemaConsulting.ReqStream processes requirements.yaml and the TRX test-result files to - produce a requirements report, justifications document, and traceability matrix. When - run with --enforce, it exits with a non-zero code if any requirement lacks test evidence, - making unproven requirements a build-breaking condition. A successful pipeline run with - --enforce proves all requirements are covered and that ReqStream is functioning. - tests: - - ReqStream_EnforcementMode - - - id: SpdxModel-OTS-BuildMark - title: BuildMark shall generate build-notes documentation from GitHub Actions metadata. - tags: - - ots - justification: | - DemaConsulting.BuildMark queries the GitHub API to capture workflow run details and - renders them as a markdown build-notes document included in the release artifacts. - It runs as part of the same CI pipeline that produces the TRX test results, so a - successful pipeline run is evidence that BuildMark executed without error. - tests: - - BuildMark_MarkdownReportGeneration - - - id: SpdxModel-OTS-VersionMark - title: VersionMark shall publish captured tool-version information. - tags: - - ots - justification: | - DemaConsulting.VersionMark reads version metadata for each dotnet tool used in the - pipeline and writes a versions markdown document included in the release artifacts. - It runs in the same CI pipeline that produces the TRX test results, so a successful - pipeline run is evidence that VersionMark executed without error. - tests: - - VersionMark_CapturesVersions - - VersionMark_GeneratesMarkdownReport - - - id: SpdxModel-OTS-SarifMark - title: SarifMark shall convert CodeQL SARIF results into a markdown report. - tags: - - ots - justification: | - DemaConsulting.SarifMark reads the SARIF output produced by CodeQL code scanning and - renders it as a human-readable markdown document included in the release artifacts. - It runs in the same CI pipeline that produces the TRX test results, so a successful - pipeline run is evidence that SarifMark executed without error. - tests: - - SarifMark_SarifReading - - SarifMark_MarkdownReportGeneration - - - id: SpdxModel-OTS-SonarMark - title: SonarMark shall generate a SonarCloud quality report. - tags: - - ots - justification: | - DemaConsulting.SonarMark retrieves quality-gate and metrics data from SonarCloud and - renders it as a markdown document included in the release artifacts. It runs in the - same CI pipeline that produces the TRX test results, so a successful pipeline run is - evidence that SonarMark executed without error. - tests: - - SonarMark_QualityGateRetrieval - - SonarMark_IssuesRetrieval - - SonarMark_HotSpotsRetrieval - - SonarMark_MarkdownReportGeneration +# This file is the root requirements file that includes all subsystem requirements. +# Requirements are split into separate files under docs/reqstream/ mirroring the source structure. + +includes: + - docs/reqstream/io/io.yaml + - docs/reqstream/system.yaml + - docs/reqstream/platform-requirements.yaml + - docs/reqstream/transform/transform.yaml + - docs/reqstream/ots/ots.yaml From ab3e275f3aa588528d370036b2cbeb353a39dd6c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 2 Apr 2026 19:41:31 +0000 Subject: [PATCH 2/8] Add unit-level design docs and split unit requirements into individual files Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .reviewmark.yaml | 30 ++++ docs/design/io/spdx-2-json-deserializer.md | 35 ++++ docs/design/io/spdx-2-json-serializer.md | 35 ++++ docs/design/io/spdx-constants.md | 24 +++ docs/design/spdx-annotation.md | 32 ++++ docs/design/spdx-checksum.md | 29 ++++ docs/design/spdx-creation-information.md | 30 ++++ docs/design/spdx-document.md | 46 ++++++ docs/design/spdx-element.md | 29 ++++ .../spdx-external-document-reference.md | 31 ++++ docs/design/spdx-external-reference.md | 32 ++++ docs/design/spdx-extracted-licensing-info.md | 33 ++++ docs/design/spdx-file.md | 37 +++++ docs/design/spdx-helpers.md | 29 ++++ docs/design/spdx-license-element.md | 30 ++++ docs/design/spdx-package-verification-code.md | 29 ++++ docs/design/spdx-package.md | 42 +++++ docs/design/spdx-relationship.md | 36 ++++ docs/design/spdx-snippet.md | 37 +++++ docs/design/transform/spdx-relationships.md | 30 ++++ docs/reqstream/spdx-annotation.yaml | 21 +++ docs/reqstream/spdx-checksum.yaml | 21 +++ docs/reqstream/spdx-creation-information.yaml | 20 +++ .../spdx-external-document-reference.yaml | 21 +++ docs/reqstream/spdx-external-reference.yaml | 21 +++ .../spdx-extracted-licensing-info.yaml | 21 +++ docs/reqstream/spdx-file.yaml | 21 +++ .../spdx-package-verification-code.yaml | 21 +++ docs/reqstream/spdx-package.yaml | 21 +++ docs/reqstream/spdx-relationship.yaml | 21 +++ docs/reqstream/spdx-snippet.yaml | 21 +++ docs/reqstream/system.yaml | 155 +----------------- requirements.yaml | 11 ++ 33 files changed, 898 insertions(+), 154 deletions(-) create mode 100644 docs/design/io/spdx-2-json-deserializer.md create mode 100644 docs/design/io/spdx-2-json-serializer.md create mode 100644 docs/design/io/spdx-constants.md create mode 100644 docs/design/spdx-annotation.md create mode 100644 docs/design/spdx-checksum.md create mode 100644 docs/design/spdx-creation-information.md create mode 100644 docs/design/spdx-document.md create mode 100644 docs/design/spdx-element.md create mode 100644 docs/design/spdx-external-document-reference.md create mode 100644 docs/design/spdx-external-reference.md create mode 100644 docs/design/spdx-extracted-licensing-info.md create mode 100644 docs/design/spdx-file.md create mode 100644 docs/design/spdx-helpers.md create mode 100644 docs/design/spdx-license-element.md create mode 100644 docs/design/spdx-package-verification-code.md create mode 100644 docs/design/spdx-package.md create mode 100644 docs/design/spdx-relationship.md create mode 100644 docs/design/spdx-snippet.md create mode 100644 docs/design/transform/spdx-relationships.md create mode 100644 docs/reqstream/spdx-annotation.yaml create mode 100644 docs/reqstream/spdx-checksum.yaml create mode 100644 docs/reqstream/spdx-creation-information.yaml create mode 100644 docs/reqstream/spdx-external-document-reference.yaml create mode 100644 docs/reqstream/spdx-external-reference.yaml create mode 100644 docs/reqstream/spdx-extracted-licensing-info.yaml create mode 100644 docs/reqstream/spdx-file.yaml create mode 100644 docs/reqstream/spdx-package-verification-code.yaml create mode 100644 docs/reqstream/spdx-package.yaml create mode 100644 docs/reqstream/spdx-relationship.yaml create mode 100644 docs/reqstream/spdx-snippet.yaml diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 06ced4d..9bc1edb 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -31,6 +31,32 @@ reviews: - "docs/reqstream/system.yaml" - "docs/design/introduction.md" - "docs/design/system.md" + - "docs/reqstream/spdx-annotation.yaml" + - "docs/reqstream/spdx-checksum.yaml" + - "docs/reqstream/spdx-creation-information.yaml" + - "docs/reqstream/spdx-external-document-reference.yaml" + - "docs/reqstream/spdx-external-reference.yaml" + - "docs/reqstream/spdx-extracted-licensing-info.yaml" + - "docs/reqstream/spdx-file.yaml" + - "docs/reqstream/spdx-package.yaml" + - "docs/reqstream/spdx-package-verification-code.yaml" + - "docs/reqstream/spdx-relationship.yaml" + - "docs/reqstream/spdx-snippet.yaml" + - "docs/design/spdx-annotation.md" + - "docs/design/spdx-checksum.md" + - "docs/design/spdx-creation-information.md" + - "docs/design/spdx-document.md" + - "docs/design/spdx-element.md" + - "docs/design/spdx-external-document-reference.md" + - "docs/design/spdx-external-reference.md" + - "docs/design/spdx-extracted-licensing-info.md" + - "docs/design/spdx-file.md" + - "docs/design/spdx-helpers.md" + - "docs/design/spdx-license-element.md" + - "docs/design/spdx-package.md" + - "docs/design/spdx-package-verification-code.md" + - "docs/design/spdx-relationship.md" + - "docs/design/spdx-snippet.md" - id: SpdxModel-Design title: SpdxModel Design Review @@ -50,6 +76,9 @@ reviews: paths: - "docs/reqstream/io/io.yaml" - "docs/design/io/io.md" + - "docs/design/io/spdx-2-json-deserializer.md" + - "docs/design/io/spdx-2-json-serializer.md" + - "docs/design/io/spdx-constants.md" - "src/DemaConsulting.SpdxModel/IO/Spdx2JsonDeserializer.cs" - "src/DemaConsulting.SpdxModel/IO/Spdx2JsonSerializer.cs" - "src/DemaConsulting.SpdxModel/IO/SpdxConstants.cs" @@ -60,5 +89,6 @@ reviews: paths: - "docs/reqstream/transform/transform.yaml" - "docs/design/transform/transform.md" + - "docs/design/transform/spdx-relationships.md" - "src/DemaConsulting.SpdxModel/Transform/SpdxRelationships.cs" - "test/DemaConsulting.SpdxModel.Tests/Transforms/SpdxRelationshipsTests.cs" diff --git a/docs/design/io/spdx-2-json-deserializer.md b/docs/design/io/spdx-2-json-deserializer.md new file mode 100644 index 0000000..bf6e856 --- /dev/null +++ b/docs/design/io/spdx-2-json-deserializer.md @@ -0,0 +1,35 @@ +# Spdx2JsonDeserializer Unit Design + +## Purpose + +`Spdx2JsonDeserializer` reads SPDX 2.x JSON documents and populates the in-memory `SpdxDocument` +object model. It supports both the SPDX 2.2 and SPDX 2.3 JSON schemas, handling version +differences transparently during parsing. + +## Design + +`Spdx2JsonDeserializer` is a public static class with no instance state. All public entry points +accept either a JSON string or a `JsonNode` and return strongly typed model objects. + +Key design decisions: + +- DOM-based parsing via `System.Text.Json.Nodes` (`JsonNode`/`JsonArray`) to allow forward + references between document elements before the full document is assembled. +- Graceful handling of optional SPDX fields: missing properties result in default values rather + than exceptions. +- Per-element `Deserialize*` methods (`DeserializePackage`, `DeserializeFile`, etc.) are public + to support targeted unit testing and partial deserialization. + +Key methods: + +| Method | Description | +| ------ | ----------- | +| `Deserialize(string)` | Entry point — parses a raw JSON string into an `SpdxDocument` | +| `DeserializeDocument(JsonNode)` | Converts a parsed `JsonNode` tree into an `SpdxDocument` | +| `Deserialize*(JsonNode?)` | Per-element helpers for each SPDX element type | + +## Dependencies + +- `System.Text.Json` (BCL) — JSON DOM parsing via `JsonNode` +- `SpdxDocument` and all data model units in the root namespace +- `SpdxConstants` — string constants for JSON property names diff --git a/docs/design/io/spdx-2-json-serializer.md b/docs/design/io/spdx-2-json-serializer.md new file mode 100644 index 0000000..e40ca4f --- /dev/null +++ b/docs/design/io/spdx-2-json-serializer.md @@ -0,0 +1,35 @@ +# Spdx2JsonSerializer Unit Design + +## Purpose + +`Spdx2JsonSerializer` converts an in-memory `SpdxDocument` object model to an SPDX 2.3 JSON +string. It is the counterpart to `Spdx2JsonDeserializer` and completes the round-trip +serialization support for the IO subsystem. + +## Design + +`Spdx2JsonSerializer` is a public static class with no instance state. All public methods +accept strongly typed model objects and return `JsonObject`/`JsonArray` nodes or a final JSON +string. + +Key design decisions: + +- Output conforms to SPDX 2.3 JSON schema. +- Optional fields are omitted entirely (not written as `null`) when empty or null to keep + output concise and compatible with strict schema validators. +- Per-element `Serialize*` methods (`SerializePackage`, `SerializeFile`, etc.) are public to + support targeted unit testing and partial serialization. + +Key methods: + +| Method | Description | +| ------ | ----------- | +| `Serialize(SpdxDocument)` | Entry point — returns a complete SPDX JSON string | +| `SerializeDocument(SpdxDocument)` | Converts an `SpdxDocument` to a `JsonObject` | +| `Serialize*(…)` | Per-element helpers for each SPDX element type | + +## Dependencies + +- `System.Text.Json` (BCL) — JSON node construction via `JsonObject`/`JsonArray` +- `SpdxDocument` and all data model units in the root namespace +- `SpdxConstants` — string constants for JSON property names diff --git a/docs/design/io/spdx-constants.md b/docs/design/io/spdx-constants.md new file mode 100644 index 0000000..76a4a5d --- /dev/null +++ b/docs/design/io/spdx-constants.md @@ -0,0 +1,24 @@ +# SpdxConstants Unit Design + +## Purpose + +`SpdxConstants` is a static class that centralizes all JSON property-name strings used when +serializing and deserializing SPDX 2.x JSON documents. It eliminates hard-coded string literals +scattered throughout the IO subsystem and provides a single place to update field names if the +specification changes. + +## Design + +`SpdxConstants` is a non-instantiable static class containing only `public const string` fields. +Each constant corresponds to one JSON property name in the SPDX 2.x JSON schema (e.g., +`FieldSpdxId`, `FieldName`, `FieldVersionInfo`). + +Key design decisions: + +- All constants are `const string` to allow use as switch-case labels and compile-time + embedding. +- No logic or state — purely a name registry. + +## Dependencies + +- None (no external dependencies; consumed by `Spdx2JsonDeserializer` and `Spdx2JsonSerializer`) diff --git a/docs/design/spdx-annotation.md b/docs/design/spdx-annotation.md new file mode 100644 index 0000000..be8f86b --- /dev/null +++ b/docs/design/spdx-annotation.md @@ -0,0 +1,32 @@ +# SpdxAnnotation Unit Design + +## Purpose + +`SpdxAnnotation` represents an SPDX annotation — a comment or review note attached to any SPDX +element by a person, organization, or tool. Annotations support compliance workflows where +reviewers document findings about software components. + +## Design + +`SpdxAnnotation` is a sealed class that extends `SpdxElement` (inheriting the `Id` field). + +Data members: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| `Annotator` | `string` | Person, organization, or tool that made the annotation | +| `Date` | `string` | ISO 8601 UTC timestamp of the annotation | +| `Type` | `SpdxAnnotationType` | Enumerated annotation type (Review, Other) | +| `Comment` | `string` | Free-text annotation content | + +Key methods: + +- `DeepCopy()` — returns a new `SpdxAnnotation` with all fields copied +- `Enhance(SpdxAnnotation)` — fills in missing fields from another instance +- `Validate(List)` — appends validation issues to the supplied list +- `Same` — static `IEqualityComparer` comparing annotator, date, type, and comment + +## Dependencies + +- `SpdxElement` (base class) +- `SpdxAnnotationType` (enum) diff --git a/docs/design/spdx-checksum.md b/docs/design/spdx-checksum.md new file mode 100644 index 0000000..46b78ae --- /dev/null +++ b/docs/design/spdx-checksum.md @@ -0,0 +1,29 @@ +# SpdxChecksum Unit Design + +## Purpose + +`SpdxChecksum` represents an SPDX checksum — an algorithm-value pair used to verify the +integrity of files and packages. Supporting multiple algorithms provides flexibility across +different security policies and tooling ecosystems. + +## Design + +`SpdxChecksum` is a sealed class with no base class (not an `SpdxElement`). + +Data members: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| `Algorithm` | `SpdxChecksumAlgorithm` | Identifies the hash algorithm (SHA1, SHA256, MD5, etc.) | +| `Value` | `string` | Lower-case hexadecimal digest value | + +Key methods: + +- `DeepCopy()` — returns a new `SpdxChecksum` with all fields copied +- `Enhance(SpdxChecksum)` — fills in missing fields from another instance +- `Validate(string, List)` — appends validation issues to the supplied list +- `Same` — static `IEqualityComparer` comparing algorithm and value + +## Dependencies + +- `SpdxChecksumAlgorithm` (enum) diff --git a/docs/design/spdx-creation-information.md b/docs/design/spdx-creation-information.md new file mode 100644 index 0000000..d301c5a --- /dev/null +++ b/docs/design/spdx-creation-information.md @@ -0,0 +1,30 @@ +# SpdxCreationInformation Unit Design + +## Purpose + +`SpdxCreationInformation` captures the metadata about who created an SPDX document and when. +One instance is required per SPDX document. It enables provenance tracing and forward/backward +compatibility for processing tools. + +## Design + +`SpdxCreationInformation` is a sealed class with no base class. + +Data members: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| `Creators` | `string[]` | Identifies the persons, organizations, or tools that created the document | +| `Created` | `string` | ISO 8601 UTC timestamp of document creation | +| `Comment` | `string?` | Optional creator comment | +| `LicenseListVersion` | `string?` | Optional SPDX license list version used | + +Key methods: + +- `DeepCopy()` — returns a new `SpdxCreationInformation` with all fields copied +- `Enhance(SpdxCreationInformation)` — fills in missing fields from another instance +- `Validate(List)` — appends validation issues; validates `Created` format via regex + +## Dependencies + +- `System.Text.RegularExpressions` — used internally to validate the `LicenseListVersion` field format diff --git a/docs/design/spdx-document.md b/docs/design/spdx-document.md new file mode 100644 index 0000000..b120766 --- /dev/null +++ b/docs/design/spdx-document.md @@ -0,0 +1,46 @@ +# SpdxDocument Unit Design + +## Purpose + +`SpdxDocument` is the root container of the SPDX object model. It aggregates all SPDX elements +(packages, files, snippets, relationships, annotations, and extracted licensing information) +and exposes document-level operations such as validation, deep copy, and root-package retrieval. + +## Design + +`SpdxDocument` is a sealed class that extends `SpdxElement` (inheriting the `Id` field). + +Data members (key fields): + +| Property | Type | Description | +| -------- | ---- | ----------- | +| `Name` | `string` | Document name | +| `Version` | `string` | SPDX specification version (e.g., `SPDX-2.3`) | +| `DataLicense` | `string` | License for the SPDX metadata itself | +| `DocumentNamespace` | `string` | Unique URI namespace for this document | +| `CreationInformation` | `SpdxCreationInformation` | Creation metadata | +| `ExternalDocumentReferences` | `SpdxExternalDocumentReference[]` | References to external SPDX documents | +| `ExtractedLicensingInfo` | `SpdxExtractedLicensingInfo[]` | Non-standard license texts | +| `Packages` | `SpdxPackage[]` | All packages in the document | +| `Files` | `SpdxFile[]` | All files in the document | +| `Snippets` | `SpdxSnippet[]` | All snippets in the document | +| `Relationships` | `SpdxRelationship[]` | All relationships in the document | +| `Annotations` | `SpdxAnnotation[]` | All annotations in the document | +| `Describes` | `string[]` | IDs of elements described by this document | + +Key methods: + +- `DeepCopy()` — returns a fully independent deep copy of the entire document graph +- `Validate(List, bool ntia)` — validates all contained elements; optional NTIA SBOM minimum elements check +- `GetRootPackages()` — returns packages directly described by the document via `DESCRIBES` relationships +- `GetAllElements()` — enumerates all contained `SpdxElement` instances +- `GetElement(string id)` / `GetElement(string id)` — retrieves an element by SPDX ID +- `Same` — static `IEqualityComparer` comparing by document name + +## Dependencies + +- `SpdxElement` (base class) +- All other data model units: `SpdxPackage`, `SpdxFile`, `SpdxSnippet`, `SpdxRelationship`, + `SpdxAnnotation`, `SpdxCreationInformation`, `SpdxExternalDocumentReference`, + `SpdxExtractedLicensingInfo` +- `System.Text.RegularExpressions` — version field format validation diff --git a/docs/design/spdx-element.md b/docs/design/spdx-element.md new file mode 100644 index 0000000..638b51c --- /dev/null +++ b/docs/design/spdx-element.md @@ -0,0 +1,29 @@ +# SpdxElement Unit Design + +## Purpose + +`SpdxElement` is the abstract base class for all identifiable SPDX elements. It defines the +common `Id` property (`SPDXRef-…`) and the shared `EnhanceElement` helper, ensuring consistent +identity handling across all element types. + +## Design + +`SpdxElement` is a public abstract class. Concrete element types (`SpdxDocument`, `SpdxPackage`, +`SpdxFile`, `SpdxSnippet`, `SpdxRelationship`, `SpdxAnnotation`) inherit from it. + +Data members: + +| Member | Type | Description | +| ------ | ---- | ----------- | +| `Id` | `string` | SPDX element identifier in `SPDXRef-` format | +| `NoAssertion` | `const string` | The sentinel value `"NOASSERTION"` used by optional fields | +| `SpdxRefRegex` | `protected static Regex` | Validates `SPDXRef-…` format | + +Key methods: + +- `EnhanceElement(SpdxElement)` — protected helper that populates `Id` from another element if currently empty + +## Dependencies + +- `System.Text.RegularExpressions` — `SpdxRefRegex` for ID validation +- `SpdxHelpers` — `EnhanceString` utility used in `EnhanceElement` diff --git a/docs/design/spdx-external-document-reference.md b/docs/design/spdx-external-document-reference.md new file mode 100644 index 0000000..2641ea9 --- /dev/null +++ b/docs/design/spdx-external-document-reference.md @@ -0,0 +1,31 @@ +# SpdxExternalDocumentReference Unit Design + +## Purpose + +`SpdxExternalDocumentReference` represents a reference from one SPDX document to another, +enabling modular SBOM construction and cross-document element referencing. Each reference +includes a checksum to verify the referenced document's integrity. + +## Design + +`SpdxExternalDocumentReference` is a sealed class with no base class (not an `SpdxElement`). + +Data members: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| `ExternalDocumentId` | `string` | Local identifier for the referenced document (e.g., `DocumentRef-tools`) | +| `Document` | `string` | URI of the referenced SPDX document | +| `Checksum` | `SpdxChecksum` | Checksum of the referenced document for integrity verification | + +Key methods: + +- `DeepCopy()` — returns a new instance with all fields deep-copied +- `Enhance(SpdxExternalDocumentReference)` — fills in missing fields from another instance +- `Enhance(array, array)` — static method merging two arrays by matching on `ExternalDocumentId` +- `Validate(List)` — appends validation issues to the supplied list +- `Same` — static `IEqualityComparer` comparing by `ExternalDocumentId` + +## Dependencies + +- `SpdxChecksum` — integrity checksum for the referenced document diff --git a/docs/design/spdx-external-reference.md b/docs/design/spdx-external-reference.md new file mode 100644 index 0000000..8335b64 --- /dev/null +++ b/docs/design/spdx-external-reference.md @@ -0,0 +1,32 @@ +# SpdxExternalReference Unit Design + +## Purpose + +`SpdxExternalReference` represents a link from an SPDX package to an external resource, such as +a package registry URL, vulnerability database entry, or documentation site. External references +enrich SBOMs with contextual information from authoritative sources. + +## Design + +`SpdxExternalReference` is a sealed class with no base class. + +Data members: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| `Category` | `SpdxReferenceCategory` | Broad category (e.g., SECURITY, PACKAGE-MANAGER) | +| `Type` | `string` | Specific reference type within the category (e.g., `cpe23Type`, `purl`) | +| `Locator` | `string` | URI or identifier for the external resource | +| `Comment` | `string?` | Optional explanatory comment | + +Key methods: + +- `DeepCopy()` — returns a new instance with all fields copied +- `Enhance(SpdxExternalReference)` — fills in missing fields from another instance +- `Enhance(array, array)` — static method merging two arrays by matching on category, type, and locator +- `Validate(string, List)` — validates the reference; `string` parameter is the owning package name +- `Same` — static `IEqualityComparer` comparing by category, type, and locator + +## Dependencies + +- `SpdxReferenceCategory` (enum) diff --git a/docs/design/spdx-extracted-licensing-info.md b/docs/design/spdx-extracted-licensing-info.md new file mode 100644 index 0000000..5ada559 --- /dev/null +++ b/docs/design/spdx-extracted-licensing-info.md @@ -0,0 +1,33 @@ +# SpdxExtractedLicensingInfo Unit Design + +## Purpose + +`SpdxExtractedLicensingInfo` records the full text and metadata of a non-standard license found +within a software package. It is used when the license does not appear on the SPDX License List +and must be captured verbatim for compliance purposes. + +## Design + +`SpdxExtractedLicensingInfo` is a sealed class with no base class. + +Data members: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| `LicenseId` | `string` | Local identifier in `LicenseRef-…` format | +| `ExtractedText` | `string` | Full verbatim text of the license | +| `Name` | `string?` | Optional human-readable license name | +| `CrossReferences` | `string[]` | Optional URIs to the license text elsewhere | +| `Comment` | `string?` | Optional explanatory comment | + +Key methods: + +- `DeepCopy()` — returns a new instance with all fields deep-copied +- `Enhance(SpdxExtractedLicensingInfo)` — fills in missing fields from another instance +- `Enhance(array, array)` — static method merging two arrays by matching on `LicenseId` +- `Validate(List)` — appends validation issues to the supplied list +- `Same` — static `IEqualityComparer` comparing by `LicenseId` + +## Dependencies + +- No external dependencies beyond base .NET BCL types diff --git a/docs/design/spdx-file.md b/docs/design/spdx-file.md new file mode 100644 index 0000000..f639c37 --- /dev/null +++ b/docs/design/spdx-file.md @@ -0,0 +1,37 @@ +# SpdxFile Unit Design + +## Purpose + +`SpdxFile` represents an individual file within an SPDX document, enabling fine-grained tracking +of source files, binaries, and other artifacts together with their licensing, checksums, and +contributor information. + +## Design + +`SpdxFile` is a sealed class that extends `SpdxLicenseElement` (which extends `SpdxElement`), +inheriting `Id`, `ConcludedLicense`, `CopyrightText`, and related license fields. + +Data members (beyond inherited fields): + +| Property | Type | Description | +| -------- | ---- | ----------- | +| `FileName` | `string` | Relative path of the file (e.g., `./src/main.c`) | +| `FileTypes` | `SpdxFileType[]` | File type classifications (SOURCE, BINARY, etc.) | +| `Checksums` | `SpdxChecksum[]` | Integrity checksums for the file | +| `LicenseInfoInFiles` | `string[]` | License expressions found in the file | +| `Comment` | `string?` | Optional comment | +| `Notice` | `string?` | Optional copyright notice text | +| `Contributors` | `string[]` | Contributors to this file | + +Key methods: + +- `DeepCopy()` — returns a fully deep-copied instance +- `Enhance(SpdxFile)` — fills in missing fields from another instance +- `Enhance(array, array)` — static method merging two file arrays, matching on `FileName` +- `Validate(List)` — appends validation issues to the supplied list +- `Same` — static `IEqualityComparer` comparing by `FileName` + +## Dependencies + +- `SpdxLicenseElement` (base class) +- `SpdxChecksum`, `SpdxFileType` (enum) diff --git a/docs/design/spdx-helpers.md b/docs/design/spdx-helpers.md new file mode 100644 index 0000000..62f33fe --- /dev/null +++ b/docs/design/spdx-helpers.md @@ -0,0 +1,29 @@ +# SpdxHelpers Unit Design + +## Purpose + +`SpdxHelpers` is an internal static utility class providing shared helper methods used across +the data model. It centralizes common operations such as string enhancement (choosing the first +non-empty value) and SPDX date-time validation. + +## Design + +`SpdxHelpers` is a `partial` internal static class using a source-generated `Regex` for +date-time validation (C# 7+ `GeneratedRegex` pattern). + +Key methods: + +| Method | Description | +| ------ | ----------- | +| `IsValidSpdxDateTime(string?)` | Returns `true` if the value matches ISO 8601 UTC format | +| `EnhanceString(params string?[])` | Returns the first non-null, non-empty string from the arguments, or `null` | + +Key design decisions: + +- `internal` visibility — not part of the public API; only used within the assembly. +- `partial` class enables the `[GeneratedRegex]` attribute on the regex factory method for + AOT-safe compiled regular expressions. + +## Dependencies + +- `System.Text.RegularExpressions` — date-time validation regex diff --git a/docs/design/spdx-license-element.md b/docs/design/spdx-license-element.md new file mode 100644 index 0000000..6c08321 --- /dev/null +++ b/docs/design/spdx-license-element.md @@ -0,0 +1,30 @@ +# SpdxLicenseElement Unit Design + +## Purpose + +`SpdxLicenseElement` is an abstract intermediate base class that adds license-related fields to +`SpdxElement`. It is the common ancestor of `SpdxPackage`, `SpdxFile`, and `SpdxSnippet`, +avoiding duplication of the concluded-license, copyright, and attribution fields. + +## Design + +`SpdxLicenseElement` is a public abstract class that extends `SpdxElement`. + +Data members (beyond `SpdxElement.Id`): + +| Property | Type | Description | +| -------- | ---- | ----------- | +| `ConcludedLicense` | `string` | License expression concluded by the SPDX document preparer | +| `LicenseComments` | `string?` | Explanation of the concluded license choice | +| `CopyrightText` | `string` | Copyright declarations text | +| `AttributionText` | `string[]` | Attribution notices required for use | + +Key design decisions: + +- Abstract (non-instantiable) — no direct consumers; always subclassed. +- Provides `EnhanceLicenseElement(SpdxLicenseElement)` protected helper analogous to + `SpdxElement.EnhanceElement` for consistent field merging. + +## Dependencies + +- `SpdxElement` (base class) diff --git a/docs/design/spdx-package-verification-code.md b/docs/design/spdx-package-verification-code.md new file mode 100644 index 0000000..d2d4d8f --- /dev/null +++ b/docs/design/spdx-package-verification-code.md @@ -0,0 +1,29 @@ +# SpdxPackageVerificationCode Unit Design + +## Purpose + +`SpdxPackageVerificationCode` represents an SPDX package verification code — a SHA1 digest +computed over the contents of a package (optionally excluding specified files). It provides +cryptographic assurance that package contents have not been modified. + +## Design + +`SpdxPackageVerificationCode` is a sealed class with no base class. + +Data members: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| `Value` | `string` | SHA1 hex digest of the package contents | +| `ExcludedFiles` | `string[]` | Files excluded from the verification code computation | + +Key methods: + +- `DeepCopy()` — returns a new instance with all fields deep-copied +- `Enhance(SpdxPackageVerificationCode)` — fills in missing fields from another instance +- `Validate(string, List)` — validates the code value; `string` parameter is the owning package name +- `Same` — static `IEqualityComparer` comparing by `Value` and `ExcludedFiles` + +## Dependencies + +- No external dependencies beyond base .NET BCL types diff --git a/docs/design/spdx-package.md b/docs/design/spdx-package.md new file mode 100644 index 0000000..6851f16 --- /dev/null +++ b/docs/design/spdx-package.md @@ -0,0 +1,42 @@ +# SpdxPackage Unit Design + +## Purpose + +`SpdxPackage` represents an SPDX package — the primary building block of a Software Bill of +Materials. It captures identity, provenance, licensing, verification, and dependency metadata +for a software package. + +## Design + +`SpdxPackage` is a sealed class that extends `SpdxLicenseElement`, inheriting `Id`, +`ConcludedLicense`, `CopyrightText`, and attribution fields. + +Data members (key fields beyond inherited): + +| Property | Type | Description | +| -------- | ---- | ----------- | +| `Name` | `string` | Package name | +| `Version` | `string?` | Package version string | +| `FileName` | `string?` | Filename of the package archive | +| `Supplier` / `Originator` | `string?` | Entity distributing / originating the package | +| `DownloadLocation` | `string` | URI from which the package was obtained | +| `FilesAnalyzed` | `bool?` | Whether files in the package have been analyzed | +| `VerificationCode` | `SpdxPackageVerificationCode?` | Cryptographic verification code | +| `Checksums` | `SpdxChecksum[]` | Package-level checksums | +| `LicenseInfoFromFiles` | `string[]` | Licenses found in files of the package | +| `DeclaredLicense` | `string` | License declared by the package authors | +| `ExternalReferences` | `SpdxExternalReference[]` | Links to external resources | +| `PrimaryPackagePurpose` | `string?` | Primary purpose classification | + +Key methods: + +- `DeepCopy()` — returns a fully deep-copied instance +- `Enhance(SpdxPackage)` — fills in missing fields from another instance +- `Enhance(array, array)` — static merging of two package arrays, matching on `Name` + `Version` +- `Validate(List, SpdxDocument?, bool ntia)` — full validation including NTIA minimum elements +- `Same` — static `IEqualityComparer` comparing by `Name` and `Version` + +## Dependencies + +- `SpdxLicenseElement` (base class) +- `SpdxChecksum`, `SpdxExternalReference`, `SpdxPackageVerificationCode` diff --git a/docs/design/spdx-relationship.md b/docs/design/spdx-relationship.md new file mode 100644 index 0000000..fd31528 --- /dev/null +++ b/docs/design/spdx-relationship.md @@ -0,0 +1,36 @@ +# SpdxRelationship Unit Design + +## Purpose + +`SpdxRelationship` represents a directed relationship between two SPDX elements. Relationships +define the dependency graph, containment hierarchy, and other associations between packages, +files, and snippets in an SPDX document. + +## Design + +`SpdxRelationship` is a sealed class that extends `SpdxElement` (inheriting the `Id` field, +which identifies the *source* element of the relationship). + +Data members: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| `Id` (inherited) | `string` | SPDX ID of the source element | +| `RelatedSpdxElement` | `string` | SPDX ID of the target element | +| `RelationshipType` | `SpdxRelationshipType` | Type of relationship (DESCRIBES, CONTAINS, DEPENDS_ON, etc.) | +| `Comment` | `string?` | Optional explanatory comment | + +Key methods: + +- `DeepCopy()` — returns a new instance with all fields copied +- `Enhance(SpdxRelationship)` — fills in missing fields from another instance +- `Enhance(array, array)` — static method merging two relationship arrays by source, target, and type +- `Validate(List, SpdxDocument?)` — validates element ID references exist in the document +- `Same` — static `IEqualityComparer` comparing source, target, and type +- `SameElements` — static `IEqualityComparer` comparing only source and target (ignoring type) + +## Dependencies + +- `SpdxElement` (base class) +- `SpdxRelationshipType` (enum) +- `SpdxDocument` — used during validation to resolve element IDs diff --git a/docs/design/spdx-snippet.md b/docs/design/spdx-snippet.md new file mode 100644 index 0000000..b2483d2 --- /dev/null +++ b/docs/design/spdx-snippet.md @@ -0,0 +1,37 @@ +# SpdxSnippet Unit Design + +## Purpose + +`SpdxSnippet` represents a portion of a file in an SPDX document. Snippets are used when a +specific range of bytes (or lines) within a file has different licensing or provenance from the +rest of the file, enabling granular compliance tracking for reused code segments. + +## Design + +`SpdxSnippet` is a sealed class that extends `SpdxLicenseElement`, inheriting `Id`, +`ConcludedLicense`, `CopyrightText`, and attribution fields. + +Data members (beyond inherited fields): + +| Property | Type | Description | +| -------- | ---- | ----------- | +| `SnippetFromFile` | `string` | SPDX ID of the file containing this snippet | +| `SnippetByteStart` | `int` | Inclusive start byte offset of the snippet | +| `SnippetByteEnd` | `int` | Inclusive end byte offset of the snippet | +| `SnippetLineStart` | `int` | Optional start line number | +| `SnippetLineEnd` | `int` | Optional end line number | +| `LicenseInfoInSnippet` | `string[]` | License expressions found in this snippet | +| `Comment` | `string?` | Optional comment | +| `Name` | `string?` | Optional human-readable snippet name | + +Key methods: + +- `DeepCopy()` — returns a fully deep-copied instance +- `Enhance(SpdxSnippet)` — fills in missing fields from another instance +- `Enhance(array, array)` — static method merging snippet arrays, matching on file ID and byte range +- `Validate(List)` — appends validation issues to the supplied list +- `Same` — static `IEqualityComparer` comparing by file, byte start, and byte end + +## Dependencies + +- `SpdxLicenseElement` (base class) diff --git a/docs/design/transform/spdx-relationships.md b/docs/design/transform/spdx-relationships.md new file mode 100644 index 0000000..a8f5456 --- /dev/null +++ b/docs/design/transform/spdx-relationships.md @@ -0,0 +1,30 @@ +# SpdxRelationships Unit Design + +## Purpose + +`SpdxRelationships` provides utility methods for adding SPDX relationships to an `SpdxDocument` +without duplication. It simplifies the common pattern of programmatically constructing SPDX +relationship graphs by handling deduplication automatically. + +## Design + +`SpdxRelationships` is a public static utility class with no instance state. + +Key methods: + +| Method | Description | +| ------ | ----------- | +| `Add(SpdxDocument, IEnumerable, bool)` | Adds relationships with deduplication; optional replace | +| `Add(SpdxDocument, SpdxRelationship)` | Adds a single relationship if not already present | + +Key design decisions: + +- Deduplication is performed using the `SpdxRelationship.Same` equality comparer so that the + same logical relationship (same elements and type) is never written twice. +- The optional `replace` flag on the batch overload allows callers to update existing + relationships rather than skip duplicates. + +## Dependencies + +- `SpdxDocument` — the target document whose `Relationships` array is modified +- `SpdxRelationship` — the relationship type and its `Same` equality comparer diff --git a/docs/reqstream/spdx-annotation.yaml b/docs/reqstream/spdx-annotation.yaml new file mode 100644 index 0000000..6b1235f --- /dev/null +++ b/docs/reqstream/spdx-annotation.yaml @@ -0,0 +1,21 @@ +--- +# SpdxAnnotation Unit Requirements +# +# This file defines requirements for the SpdxAnnotation unit. + +sections: + - title: SpdxAnnotation Unit Requirements + requirements: + - id: SpdxModel-Data-Annotations + title: The library shall support SPDX annotations. + tags: + - data-model + justification: | + Annotations allow adding review and assessment information to SPDX elements. This supports + compliance workflows where reviewers need to document their findings and decisions about + software components. + tests: + - SpdxAnnotation_SameComparer_ComparesCorrectly + - SpdxAnnotation_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeAnnotation_CorrectResults + - Spdx2JsonSerializer_SerializeAnnotation_CorrectResults diff --git a/docs/reqstream/spdx-checksum.yaml b/docs/reqstream/spdx-checksum.yaml new file mode 100644 index 0000000..57ce723 --- /dev/null +++ b/docs/reqstream/spdx-checksum.yaml @@ -0,0 +1,21 @@ +--- +# SpdxChecksum Unit Requirements +# +# This file defines requirements for the SpdxChecksum unit. + +sections: + - title: SpdxChecksum Unit Requirements + requirements: + - id: SpdxModel-Data-Checksums + title: The library shall support SPDX checksums with multiple algorithms. + tags: + - data-model + justification: | + Checksums with multiple algorithms provide integrity verification for files and packages. + Supporting multiple algorithms ensures flexibility and compatibility with different security + requirements and organizational policies. + tests: + - SpdxChecksum_SameComparer_ComparesCorrectly + - SpdxChecksum_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeChecksum_CorrectResults + - Spdx2JsonSerializer_SerializeChecksum_CorrectResults diff --git a/docs/reqstream/spdx-creation-information.yaml b/docs/reqstream/spdx-creation-information.yaml new file mode 100644 index 0000000..d8400b5 --- /dev/null +++ b/docs/reqstream/spdx-creation-information.yaml @@ -0,0 +1,20 @@ +--- +# SpdxCreationInformation Unit Requirements +# +# This file defines requirements for the SpdxCreationInformation unit. + +sections: + - title: SpdxCreationInformation Unit Requirements + requirements: + - id: SpdxModel-Data-CreationInformation + title: The library shall support SPDX document creation information. + tags: + - data-model + justification: | + Creation information is a required element of SPDX documents that provides metadata about + who created the document and when. Supporting this element is essential for SPDX compliance + and traceability of document provenance. + tests: + - SpdxCreationInformation_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeCreationInformation_CorrectResults + - Spdx2JsonSerializer_SerializeCreationInformation_CorrectResults diff --git a/docs/reqstream/spdx-external-document-reference.yaml b/docs/reqstream/spdx-external-document-reference.yaml new file mode 100644 index 0000000..2e7bc4a --- /dev/null +++ b/docs/reqstream/spdx-external-document-reference.yaml @@ -0,0 +1,21 @@ +--- +# SpdxExternalDocumentReference Unit Requirements +# +# This file defines requirements for the SpdxExternalDocumentReference unit. + +sections: + - title: SpdxExternalDocumentReference Unit Requirements + requirements: + - id: SpdxModel-Data-ExternalDocumentReferences + title: The library shall support SPDX external document references. + tags: + - data-model + justification: | + External document references allow SPDX documents to reference other SPDX documents, + enabling modular SBOM construction and linking between related software inventories. This + is essential for managing complex multi-component software systems. + tests: + - SpdxExternalDocumentReference_SameComparer_ComparesCorrectly + - SpdxExternalDocumentReference_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeExternalDocumentReference_CorrectResults + - Spdx2JsonSerializer_SerializeExternalDocumentReference_CorrectResults diff --git a/docs/reqstream/spdx-external-reference.yaml b/docs/reqstream/spdx-external-reference.yaml new file mode 100644 index 0000000..4c828cf --- /dev/null +++ b/docs/reqstream/spdx-external-reference.yaml @@ -0,0 +1,21 @@ +--- +# SpdxExternalReference Unit Requirements +# +# This file defines requirements for the SpdxExternalReference unit. + +sections: + - title: SpdxExternalReference Unit Requirements + requirements: + - id: SpdxModel-Data-ExternalReferences + title: The library shall support SPDX external references. + tags: + - data-model + justification: | + External references enable linking SPDX elements to external resources like package + registries, vulnerability databases, and documentation. This enriches SBOMs with contextual + information from authoritative sources. + tests: + - SpdxExternalReference_SameComparer_ComparesCorrectly + - SpdxExternalReference_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeExternalReference_CorrectResults + - Spdx2JsonSerializer_SerializeExternalReference_CorrectResults diff --git a/docs/reqstream/spdx-extracted-licensing-info.yaml b/docs/reqstream/spdx-extracted-licensing-info.yaml new file mode 100644 index 0000000..c370fd1 --- /dev/null +++ b/docs/reqstream/spdx-extracted-licensing-info.yaml @@ -0,0 +1,21 @@ +--- +# SpdxExtractedLicensingInfo Unit Requirements +# +# This file defines requirements for the SpdxExtractedLicensingInfo unit. + +sections: + - title: SpdxExtractedLicensingInfo Unit Requirements + requirements: + - id: SpdxModel-Data-ExtractedLicensingInfo + title: The library shall support SPDX extracted licensing information. + tags: + - data-model + justification: | + Extracted licensing information supports documenting non-standard licenses found in + software packages. This is critical for compliance when software contains licenses not + in the SPDX license list. + tests: + - SpdxExtractedLicensingInfo_SameComparer_ComparesCorrectly + - SpdxExtractedLicensingInfo_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeExtractedLicensingInfo_CorrectResults + - Spdx2JsonSerializer_SerializeExtractedLicensingInfo_CorrectResults diff --git a/docs/reqstream/spdx-file.yaml b/docs/reqstream/spdx-file.yaml new file mode 100644 index 0000000..a7383dd --- /dev/null +++ b/docs/reqstream/spdx-file.yaml @@ -0,0 +1,21 @@ +--- +# SpdxFile Unit Requirements +# +# This file defines requirements for the SpdxFile unit. + +sections: + - title: SpdxFile Unit Requirements + requirements: + - id: SpdxModel-Data-Files + title: The library shall support SPDX files. + tags: + - data-model + justification: | + Files are essential components in SPDX documents for detailed SBOM creation. Supporting + file elements enables fine-grained tracking of individual source files, binaries, and + their associated licensing and copyright information. + tests: + - SpdxFile_SameComparer_ComparesCorrectly + - SpdxFile_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeFile_CorrectResults + - Spdx2JsonSerializer_SerializeFile_CorrectResults diff --git a/docs/reqstream/spdx-package-verification-code.yaml b/docs/reqstream/spdx-package-verification-code.yaml new file mode 100644 index 0000000..e1afc77 --- /dev/null +++ b/docs/reqstream/spdx-package-verification-code.yaml @@ -0,0 +1,21 @@ +--- +# SpdxPackageVerificationCode Unit Requirements +# +# This file defines requirements for the SpdxPackageVerificationCode unit. + +sections: + - title: SpdxPackageVerificationCode Unit Requirements + requirements: + - id: SpdxModel-Data-PackageVerificationCodes + title: The library shall support SPDX package verification codes. + tags: + - data-model + justification: | + Package verification codes provide a way to verify package contents integrity. This + cryptographic verification mechanism is important for ensuring that package contents + have not been tampered with or corrupted. + tests: + - SpdxPackageVerificationCode_SameComparer_ComparesCorrectly + - SpdxPackageVerificationCode_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializePackageVerificationCode_CorrectResults + - Spdx2JsonSerializer_SerializePackageVerificationCode_CorrectResults diff --git a/docs/reqstream/spdx-package.yaml b/docs/reqstream/spdx-package.yaml new file mode 100644 index 0000000..0fc724c --- /dev/null +++ b/docs/reqstream/spdx-package.yaml @@ -0,0 +1,21 @@ +--- +# SpdxPackage Unit Requirements +# +# This file defines requirements for the SpdxPackage unit. + +sections: + - title: SpdxPackage Unit Requirements + requirements: + - id: SpdxModel-Data-Packages + title: The library shall support SPDX packages. + tags: + - data-model + justification: | + Packages are core elements in SPDX documents representing software packages in an SBOM. + Supporting package elements is fundamental to the library's purpose of managing software + bill of materials and dependency information. + tests: + - SpdxPackage_SameComparer_ComparesCorrectly + - SpdxPackage_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializePackage_CorrectResults + - Spdx2JsonSerializer_SerializePackage_CorrectResults diff --git a/docs/reqstream/spdx-relationship.yaml b/docs/reqstream/spdx-relationship.yaml new file mode 100644 index 0000000..f2d20a0 --- /dev/null +++ b/docs/reqstream/spdx-relationship.yaml @@ -0,0 +1,21 @@ +--- +# SpdxRelationship Unit Requirements +# +# This file defines requirements for the SpdxRelationship unit. + +sections: + - title: SpdxRelationship Unit Requirements + requirements: + - id: SpdxModel-Data-Relationships + title: The library shall support SPDX relationships. + tags: + - data-model + justification: | + Relationships define connections between SPDX elements and are critical for expressing + dependency graphs, containment hierarchies, and other associations in SBOMs. This is + fundamental to representing complex software structures. + tests: + - SpdxRelationship_SameComparer_ComparesCorrectly + - SpdxRelationship_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeRelationship_CorrectResults + - Spdx2JsonSerializer_SerializeRelationship_CorrectResults diff --git a/docs/reqstream/spdx-snippet.yaml b/docs/reqstream/spdx-snippet.yaml new file mode 100644 index 0000000..b44ff7c --- /dev/null +++ b/docs/reqstream/spdx-snippet.yaml @@ -0,0 +1,21 @@ +--- +# SpdxSnippet Unit Requirements +# +# This file defines requirements for the SpdxSnippet unit. + +sections: + - title: SpdxSnippet Unit Requirements + requirements: + - id: SpdxModel-Data-Snippets + title: The library shall support SPDX snippets. + tags: + - data-model + justification: | + Snippets represent portions of files and are important for documenting code reuse at a + granular level. This supports compliance scenarios where specific code segments have + different licensing or provenance than their containing files. + tests: + - SpdxSnippet_SameComparer_ComparesCorrectly + - SpdxSnippet_DeepCopy_CreatesEqualButDistinctInstance + - Spdx2JsonDeserializer_DeserializeSnippet_CorrectResults + - Spdx2JsonSerializer_SerializeSnippet_CorrectResults diff --git a/docs/reqstream/system.yaml b/docs/reqstream/system.yaml index e78570e..ed2a63d 100644 --- a/docs/reqstream/system.yaml +++ b/docs/reqstream/system.yaml @@ -1,7 +1,7 @@ --- # SpdxModel System Requirements # -# This file defines the system-level data model and validation requirements +# This file defines the system-level and cross-cutting requirements # for the SpdxModel library. sections: @@ -9,159 +9,6 @@ sections: sections: - title: Data Model requirements: - - id: SpdxModel-Data-CreationInformation - title: The library shall support SPDX document creation information. - tags: - - data-model - justification: | - Creation information is a required element of SPDX documents that provides metadata about - who created the document and when. Supporting this element is essential for SPDX compliance - and traceability of document provenance. - tests: - - SpdxCreationInformation_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeCreationInformation_CorrectResults - - Spdx2JsonSerializer_SerializeCreationInformation_CorrectResults - - - id: SpdxModel-Data-Packages - title: The library shall support SPDX packages. - tags: - - data-model - justification: | - Packages are core elements in SPDX documents representing software packages in an SBOM. - Supporting package elements is fundamental to the library's purpose of managing software - bill of materials and dependency information. - tests: - - SpdxPackage_SameComparer_ComparesCorrectly - - SpdxPackage_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializePackage_CorrectResults - - Spdx2JsonSerializer_SerializePackage_CorrectResults - - - id: SpdxModel-Data-Files - title: The library shall support SPDX files. - tags: - - data-model - justification: | - Files are essential components in SPDX documents for detailed SBOM creation. Supporting - file elements enables fine-grained tracking of individual source files, binaries, and - their associated licensing and copyright information. - tests: - - SpdxFile_SameComparer_ComparesCorrectly - - SpdxFile_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeFile_CorrectResults - - Spdx2JsonSerializer_SerializeFile_CorrectResults - - - id: SpdxModel-Data-Snippets - title: The library shall support SPDX snippets. - tags: - - data-model - justification: | - Snippets represent portions of files and are important for documenting code reuse at a - granular level. This supports compliance scenarios where specific code segments have - different licensing or provenance than their containing files. - tests: - - SpdxSnippet_SameComparer_ComparesCorrectly - - SpdxSnippet_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeSnippet_CorrectResults - - Spdx2JsonSerializer_SerializeSnippet_CorrectResults - - - id: SpdxModel-Data-Relationships - title: The library shall support SPDX relationships. - tags: - - data-model - justification: | - Relationships define connections between SPDX elements and are critical for expressing - dependency graphs, containment hierarchies, and other associations in SBOMs. This is - fundamental to representing complex software structures. - tests: - - SpdxRelationship_SameComparer_ComparesCorrectly - - SpdxRelationship_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeRelationship_CorrectResults - - Spdx2JsonSerializer_SerializeRelationship_CorrectResults - - - id: SpdxModel-Data-Annotations - title: The library shall support SPDX annotations. - tags: - - data-model - justification: | - Annotations allow adding review and assessment information to SPDX elements. This supports - compliance workflows where reviewers need to document their findings and decisions about - software components. - tests: - - SpdxAnnotation_SameComparer_ComparesCorrectly - - SpdxAnnotation_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeAnnotation_CorrectResults - - Spdx2JsonSerializer_SerializeAnnotation_CorrectResults - - - id: SpdxModel-Data-Checksums - title: The library shall support SPDX checksums with multiple algorithms. - tags: - - data-model - justification: | - Checksums with multiple algorithms provide integrity verification for files and packages. - Supporting multiple algorithms ensures flexibility and compatibility with different security - requirements and organizational policies. - tests: - - SpdxChecksum_SameComparer_ComparesCorrectly - - SpdxChecksum_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeChecksum_CorrectResults - - Spdx2JsonSerializer_SerializeChecksum_CorrectResults - - - id: SpdxModel-Data-ExternalReferences - title: The library shall support SPDX external references. - tags: - - data-model - justification: | - External references enable linking SPDX elements to external resources like package - registries, vulnerability databases, and documentation. This enriches SBOMs with contextual - information from authoritative sources. - tests: - - SpdxExternalReference_SameComparer_ComparesCorrectly - - SpdxExternalReference_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeExternalReference_CorrectResults - - Spdx2JsonSerializer_SerializeExternalReference_CorrectResults - - - id: SpdxModel-Data-ExternalDocumentReferences - title: The library shall support SPDX external document references. - tags: - - data-model - justification: | - External document references allow SPDX documents to reference other SPDX documents, - enabling modular SBOM construction and linking between related software inventories. This - is essential for managing complex multi-component software systems. - tests: - - SpdxExternalDocumentReference_SameComparer_ComparesCorrectly - - SpdxExternalDocumentReference_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeExternalDocumentReference_CorrectResults - - Spdx2JsonSerializer_SerializeExternalDocumentReference_CorrectResults - - - id: SpdxModel-Data-ExtractedLicensingInfo - title: The library shall support SPDX extracted licensing information. - tags: - - data-model - justification: | - Extracted licensing information supports documenting non-standard licenses found in - software packages. This is critical for compliance when software contains licenses not - in the SPDX license list. - tests: - - SpdxExtractedLicensingInfo_SameComparer_ComparesCorrectly - - SpdxExtractedLicensingInfo_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializeExtractedLicensingInfo_CorrectResults - - Spdx2JsonSerializer_SerializeExtractedLicensingInfo_CorrectResults - - - id: SpdxModel-Data-PackageVerificationCodes - title: The library shall support SPDX package verification codes. - tags: - - data-model - justification: | - Package verification codes provide a way to verify package contents integrity. This - cryptographic verification mechanism is important for ensuring that package contents - have not been tampered with or corrupted. - tests: - - SpdxPackageVerificationCode_SameComparer_ComparesCorrectly - - SpdxPackageVerificationCode_DeepCopy_CreatesEqualButDistinctInstance - - Spdx2JsonDeserializer_DeserializePackageVerificationCode_CorrectResults - - Spdx2JsonSerializer_SerializePackageVerificationCode_CorrectResults - - id: SpdxModel-Data-RootPackages title: The library shall support retrieving root packages from an SPDX document. tags: diff --git a/requirements.yaml b/requirements.yaml index 30c1f05..993a6ea 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -10,3 +10,14 @@ includes: - docs/reqstream/platform-requirements.yaml - docs/reqstream/transform/transform.yaml - docs/reqstream/ots/ots.yaml + - docs/reqstream/spdx-annotation.yaml + - docs/reqstream/spdx-checksum.yaml + - docs/reqstream/spdx-creation-information.yaml + - docs/reqstream/spdx-external-document-reference.yaml + - docs/reqstream/spdx-external-reference.yaml + - docs/reqstream/spdx-extracted-licensing-info.yaml + - docs/reqstream/spdx-file.yaml + - docs/reqstream/spdx-package.yaml + - docs/reqstream/spdx-package-verification-code.yaml + - docs/reqstream/spdx-relationship.yaml + - docs/reqstream/spdx-snippet.yaml From a809af3ab3bc8e05117c54a7b6ebf5aa6ef67f90 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 2 Apr 2026 20:25:27 +0000 Subject: [PATCH 3/8] Split IO and Transform subsystem requirements into unit-level files Agent-Logs-Url: https://github.com/demaconsulting/SpdxModel/sessions/a2a5847a-367d-4435-b668-034fe42095e2 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .reviewmark.yaml | 3 ++ docs/reqstream/io/io.yaml | 41 ++----------------- .../io/spdx-2-json-deserializer.yaml | 30 ++++++++++++++ docs/reqstream/io/spdx-2-json-serializer.yaml | 19 +++++++++ .../transform/spdx-relationships.yaml | 20 +++++++++ docs/reqstream/transform/transform.yaml | 17 ++------ requirements.yaml | 3 ++ 7 files changed, 82 insertions(+), 51 deletions(-) create mode 100644 docs/reqstream/io/spdx-2-json-deserializer.yaml create mode 100644 docs/reqstream/io/spdx-2-json-serializer.yaml create mode 100644 docs/reqstream/transform/spdx-relationships.yaml diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 9bc1edb..e89ab24 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -75,6 +75,8 @@ reviews: title: SpdxModel IO Subsystem Review paths: - "docs/reqstream/io/io.yaml" + - "docs/reqstream/io/spdx-2-json-deserializer.yaml" + - "docs/reqstream/io/spdx-2-json-serializer.yaml" - "docs/design/io/io.md" - "docs/design/io/spdx-2-json-deserializer.md" - "docs/design/io/spdx-2-json-serializer.md" @@ -88,6 +90,7 @@ reviews: title: SpdxModel Transform Subsystem Review paths: - "docs/reqstream/transform/transform.yaml" + - "docs/reqstream/transform/spdx-relationships.yaml" - "docs/design/transform/transform.md" - "docs/design/transform/spdx-relationships.md" - "src/DemaConsulting.SpdxModel/Transform/SpdxRelationships.cs" diff --git a/docs/reqstream/io/io.yaml b/docs/reqstream/io/io.yaml index 20231bf..97650f6 100644 --- a/docs/reqstream/io/io.yaml +++ b/docs/reqstream/io/io.yaml @@ -1,43 +1,10 @@ --- # SpdxModel IO Subsystem Requirements # -# This file defines the serialization requirements for the IO subsystem -# of the SpdxModel library. +# This is the subsystem-level requirements file for the IO subsystem. +# Unit requirements are in the sibling unit files: +# spdx-2-json-deserializer.yaml +# spdx-2-json-serializer.yaml sections: - title: IO Subsystem Requirements - sections: - - title: Serialization - requirements: - - id: SpdxModel-Ser-Deserialize22Json - title: The library shall support deserializing SPDX 2.2 JSON documents. - tags: - - serialization - justification: | - Deserializing SPDX 2.2 JSON documents is essential for backward compatibility and - interoperability with systems using the SPDX 2.2 specification. This ensures that the - library can read and process existing SPDX 2.2 documents from various sources. - tests: - - Spdx2JsonDeserializer_Deserialize_ValidSpdx22JsonReturnsExpectedDocument - - - id: SpdxModel-Ser-Deserialize23Json - title: The library shall support deserializing SPDX 2.3 JSON documents. - tags: - - serialization - justification: | - Support for SPDX 2.3 JSON documents ensures the library remains current with the latest - SPDX specification. This allows users to leverage new features and improvements introduced - in SPDX 2.3 while maintaining compatibility with modern SBOM tools. - tests: - - Spdx2JsonDeserializer_Deserialize_ValidSpdx23JsonReturnsExpectedDocument - - - id: SpdxModel-Ser-SerializeJson - title: The library shall support serializing SPDX documents to JSON format. - tags: - - serialization - justification: | - Serialization capability is fundamental for creating and exporting SPDX documents in JSON - format. This enables users to generate SBOMs programmatically and share them with other - systems and tools in the SPDX ecosystem. - tests: - - Spdx2JsonSerializer_SerializeDocument_CorrectResults diff --git a/docs/reqstream/io/spdx-2-json-deserializer.yaml b/docs/reqstream/io/spdx-2-json-deserializer.yaml new file mode 100644 index 0000000..d6128e6 --- /dev/null +++ b/docs/reqstream/io/spdx-2-json-deserializer.yaml @@ -0,0 +1,30 @@ +--- +# SpdxModel Spdx2JsonDeserializer Unit Requirements +# +# This file defines the requirements for the Spdx2JsonDeserializer unit +# in the IO subsystem of the SpdxModel library. + +sections: + - title: Spdx2JsonDeserializer Requirements + requirements: + - id: SpdxModel-Ser-Deserialize22Json + title: The library shall support deserializing SPDX 2.2 JSON documents. + tags: + - serialization + justification: | + Deserializing SPDX 2.2 JSON documents is essential for backward compatibility and + interoperability with systems using the SPDX 2.2 specification. This ensures that the + library can read and process existing SPDX 2.2 documents from various sources. + tests: + - Spdx2JsonDeserializer_Deserialize_ValidSpdx22JsonReturnsExpectedDocument + + - id: SpdxModel-Ser-Deserialize23Json + title: The library shall support deserializing SPDX 2.3 JSON documents. + tags: + - serialization + justification: | + Support for SPDX 2.3 JSON documents ensures the library remains current with the latest + SPDX specification. This allows users to leverage new features and improvements introduced + in SPDX 2.3 while maintaining compatibility with modern SBOM tools. + tests: + - Spdx2JsonDeserializer_Deserialize_ValidSpdx23JsonReturnsExpectedDocument diff --git a/docs/reqstream/io/spdx-2-json-serializer.yaml b/docs/reqstream/io/spdx-2-json-serializer.yaml new file mode 100644 index 0000000..bdaeedd --- /dev/null +++ b/docs/reqstream/io/spdx-2-json-serializer.yaml @@ -0,0 +1,19 @@ +--- +# SpdxModel Spdx2JsonSerializer Unit Requirements +# +# This file defines the requirements for the Spdx2JsonSerializer unit +# in the IO subsystem of the SpdxModel library. + +sections: + - title: Spdx2JsonSerializer Requirements + requirements: + - id: SpdxModel-Ser-SerializeJson + title: The library shall support serializing SPDX documents to JSON format. + tags: + - serialization + justification: | + Serialization capability is fundamental for creating and exporting SPDX documents in JSON + format. This enables users to generate SBOMs programmatically and share them with other + systems and tools in the SPDX ecosystem. + tests: + - Spdx2JsonSerializer_SerializeDocument_CorrectResults diff --git a/docs/reqstream/transform/spdx-relationships.yaml b/docs/reqstream/transform/spdx-relationships.yaml new file mode 100644 index 0000000..80f0d4a --- /dev/null +++ b/docs/reqstream/transform/spdx-relationships.yaml @@ -0,0 +1,20 @@ +--- +# SpdxModel SpdxRelationships Unit Requirements +# +# This file defines the requirements for the SpdxRelationships unit +# in the Transform subsystem of the SpdxModel library. + +sections: + - title: SpdxRelationships Requirements + requirements: + - id: SpdxModel-Data-RelationshipUtilities + title: The library shall provide utilities for manipulating SPDX relationships. + tags: + - data-model + justification: | + Relationship manipulation utilities simplify common operations on SPDX documents such as + adding and managing relationships between elements. This improves developer productivity + and reduces errors when constructing complex SBOMs. + tests: + - SpdxRelationships_AddSingle_Success + - SpdxRelationships_AddMultiple_Success diff --git a/docs/reqstream/transform/transform.yaml b/docs/reqstream/transform/transform.yaml index a6e59ed..9a07ac2 100644 --- a/docs/reqstream/transform/transform.yaml +++ b/docs/reqstream/transform/transform.yaml @@ -1,20 +1,9 @@ --- # SpdxModel Transform Subsystem Requirements # -# This file defines the requirements for the Transform subsystem -# of the SpdxModel library. +# This is the subsystem-level requirements file for the Transform subsystem. +# Unit requirements are in the sibling unit file: +# spdx-relationships.yaml sections: - title: Transform Subsystem Requirements - requirements: - - id: SpdxModel-Data-RelationshipUtilities - title: The library shall provide utilities for manipulating SPDX relationships. - tags: - - data-model - justification: | - Relationship manipulation utilities simplify common operations on SPDX documents such as - adding and managing relationships between elements. This improves developer productivity - and reduces errors when constructing complex SBOMs. - tests: - - SpdxRelationships_AddSingle_Success - - SpdxRelationships_AddMultiple_Success diff --git a/requirements.yaml b/requirements.yaml index 993a6ea..457f8e9 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -6,9 +6,12 @@ includes: - docs/reqstream/io/io.yaml + - docs/reqstream/io/spdx-2-json-deserializer.yaml + - docs/reqstream/io/spdx-2-json-serializer.yaml - docs/reqstream/system.yaml - docs/reqstream/platform-requirements.yaml - docs/reqstream/transform/transform.yaml + - docs/reqstream/transform/spdx-relationships.yaml - docs/reqstream/ots/ots.yaml - docs/reqstream/spdx-annotation.yaml - docs/reqstream/spdx-checksum.yaml From c5480e32e806a98bbe5124ecd33d4194a8dae3a1 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Thu, 2 Apr 2026 17:22:48 -0400 Subject: [PATCH 4/8] Update docs/design/io/io.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/design/io/io.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/design/io/io.md b/docs/design/io/io.md index 9a9a8b2..28dd3af 100644 --- a/docs/design/io/io.md +++ b/docs/design/io/io.md @@ -19,20 +19,22 @@ to the SPDX 2.2 and 2.3 specifications. ### Spdx2JsonDeserializer `Spdx2JsonDeserializer` reads a JSON stream or string and populates a `SpdxDocument`. It uses -`System.Text.Json` `JsonDocument` for DOM-based parsing, navigating named properties to -reconstruct each element. Both SPDX 2.2 and 2.3 JSON schemas are supported; version differences -are handled transparently during parsing. +`System.Text.Json.Nodes`, parsing input with `JsonNode.Parse` and traversing `JsonObject` and +`JsonArray` nodes to reconstruct each element. Both SPDX 2.2 and 2.3 JSON schemas are +supported; version differences are handled transparently during parsing. Key design decisions: -- DOM-based parsing (rather than streaming) to allow forward references between document elements +- DOM-based parsing via `JsonNode` (rather than streaming) to allow forward references between + document elements - Graceful handling of optional SPDX fields (missing fields result in default values) ### Spdx2JsonSerializer -`Spdx2JsonSerializer` takes an `SpdxDocument` and writes it to a `Utf8JsonWriter`. It iterates -over each element collection in document order, writing the appropriate JSON structure for each -SPDX element type. +`Spdx2JsonSerializer` takes an `SpdxDocument`, builds a JSON DOM using `JsonObject` and +`JsonArray`, and emits the final JSON with `ToJsonString(...)`. It iterates over each element +collection in document order, creating the appropriate JSON structure for each SPDX element +type. Key design decisions: From e349683c8326b7fec01018fc0adbbde660baae7c Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Thu, 2 Apr 2026 17:23:51 -0400 Subject: [PATCH 5/8] Update docs/design/system.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/design/system.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/design/system.md b/docs/design/system.md index 1e05f3e..7eed5d6 100644 --- a/docs/design/system.md +++ b/docs/design/system.md @@ -19,8 +19,8 @@ representing all SPDX document elements, plus serialization and transformation c ### External Dependencies -- **System.Text.Json** — used by the IO subsystem for JSON reading and writing; available as part of - the .NET BCL from .NET 6 onwards and via NuGet for .NET Standard 2.0 +- **System.Text.Json** — used by the IO subsystem for JSON reading and writing; available in-box on + modern .NET targets and via NuGet for .NET Standard 2.0 - **.NET Standard 2.0 / .NET 8 / .NET 9 / .NET 10** — target frameworks ### Public API Surface From 9a56a128d0c5ed20687752daebfdcb5f5ae155b4 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Thu, 2 Apr 2026 17:24:13 -0400 Subject: [PATCH 6/8] Update docs/design/system.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/design/system.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/design/system.md b/docs/design/system.md index 7eed5d6..8e6edc0 100644 --- a/docs/design/system.md +++ b/docs/design/system.md @@ -53,8 +53,9 @@ Spdx2JsonDeserializer ──► SpdxDocument (in-memory model) - **Immutability by convention**: data model classes use public mutable properties to allow flexible construction while deep-copy methods provide safe cloning - **Nullable reference types enabled**: all public API members declare nullability explicitly -- **No external runtime dependencies beyond BCL**: keeps the library lightweight and avoids - dependency conflicts for consumers +- **Minimal runtime dependencies**: keeps the library lightweight and avoids dependency conflicts + for consumers by relying only on BCL/framework-provided APIs where available, with + compatibility NuGet packages used on older targets such as `netstandard2.0` - **Target multi-framework**: the library targets `netstandard2.0`, `net8.0`, `net9.0`, and `net10.0` simultaneously From f060ce0dbaf381769075dac532fe9dff9b0420b7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 2 Apr 2026 21:29:41 +0000 Subject: [PATCH 7/8] Fix design doc inaccuracies: SpdxHelpers regex/EnhanceString, Transform method names Agent-Logs-Url: https://github.com/demaconsulting/SpdxModel/sessions/3f9d1b60-7750-489d-bd33-b74c98ee503b Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- docs/design/spdx-helpers.md | 17 ++++++++++------- docs/design/transform/transform.md | 4 ++-- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/design/spdx-helpers.md b/docs/design/spdx-helpers.md index 62f33fe..2a06700 100644 --- a/docs/design/spdx-helpers.md +++ b/docs/design/spdx-helpers.md @@ -3,26 +3,29 @@ ## Purpose `SpdxHelpers` is an internal static utility class providing shared helper methods used across -the data model. It centralizes common operations such as string enhancement (choosing the first -non-empty value) and SPDX date-time validation. +the data model. It centralizes common operations such as string enhancement (selecting the +best available value by fitness ranking) and SPDX date-time validation. ## Design -`SpdxHelpers` is a `partial` internal static class using a source-generated `Regex` for -date-time validation (C# 7+ `GeneratedRegex` pattern). +`SpdxHelpers` is a `partial` internal static class. Date-time validation uses +`[GeneratedRegex]` on .NET 7 and later (source-generated, AOT-safe), with a cached `Regex` +instance as a fallback for earlier targets such as `netstandard2.0`. Key methods: | Method | Description | | ------ | ----------- | | `IsValidSpdxDateTime(string?)` | Returns `true` if the value matches ISO 8601 UTC format | -| `EnhanceString(params string?[])` | Returns the first non-null, non-empty string from the arguments, or `null` | +| `EnhanceString(params string?[])` | Returns the highest-fitness value: concrete > `NOASSERTION` > empty > `null` | Key design decisions: - `internal` visibility — not part of the public API; only used within the assembly. -- `partial` class enables the `[GeneratedRegex]` attribute on the regex factory method for - AOT-safe compiled regular expressions. +- `partial` class enables the `[GeneratedRegex]` attribute on .NET 7+; pre-.NET 7 targets use + a cached `Regex` instance instead. +- `EnhanceString` uses a fitness ranking so that a meaningful value is always preferred over + `NOASSERTION` or absent values, regardless of argument order. ## Dependencies diff --git a/docs/design/transform/transform.md b/docs/design/transform/transform.md index d5c1d98..81e11dd 100644 --- a/docs/design/transform/transform.md +++ b/docs/design/transform/transform.md @@ -21,8 +21,8 @@ manner, reducing boilerplate for consumers constructing SPDX documents programma Key methods: -- `AddRelationship` — adds a single relationship to the document if it does not already exist -- `AddRelationships` — adds multiple relationships, deduplicating against existing entries +- `Add(...)` — adds a single relationship to the document if it does not already exist +- `Add(...)` — adds multiple relationships, deduplicating against existing entries, with an optional `replace` parameter Key design decisions: From 09f5bb5ecc72496c467a81e1de96ea5860f6d9d1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 2 Apr 2026 22:35:58 +0000 Subject: [PATCH 8/8] Fix .reviewmark.yaml: slim System review-set, add 15 unit review-sets Agent-Logs-Url: https://github.com/demaconsulting/SpdxModel/sessions/0ea9f389-c10d-4275-aa36-7bdfbc07543e Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .reviewmark.yaml | 144 ++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 118 insertions(+), 26 deletions(-) diff --git a/.reviewmark.yaml b/.reviewmark.yaml index e89ab24..b7fa98d 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -31,32 +31,6 @@ reviews: - "docs/reqstream/system.yaml" - "docs/design/introduction.md" - "docs/design/system.md" - - "docs/reqstream/spdx-annotation.yaml" - - "docs/reqstream/spdx-checksum.yaml" - - "docs/reqstream/spdx-creation-information.yaml" - - "docs/reqstream/spdx-external-document-reference.yaml" - - "docs/reqstream/spdx-external-reference.yaml" - - "docs/reqstream/spdx-extracted-licensing-info.yaml" - - "docs/reqstream/spdx-file.yaml" - - "docs/reqstream/spdx-package.yaml" - - "docs/reqstream/spdx-package-verification-code.yaml" - - "docs/reqstream/spdx-relationship.yaml" - - "docs/reqstream/spdx-snippet.yaml" - - "docs/design/spdx-annotation.md" - - "docs/design/spdx-checksum.md" - - "docs/design/spdx-creation-information.md" - - "docs/design/spdx-document.md" - - "docs/design/spdx-element.md" - - "docs/design/spdx-external-document-reference.md" - - "docs/design/spdx-external-reference.md" - - "docs/design/spdx-extracted-licensing-info.md" - - "docs/design/spdx-file.md" - - "docs/design/spdx-helpers.md" - - "docs/design/spdx-license-element.md" - - "docs/design/spdx-package.md" - - "docs/design/spdx-package-verification-code.md" - - "docs/design/spdx-relationship.md" - - "docs/design/spdx-snippet.md" - id: SpdxModel-Design title: SpdxModel Design Review @@ -95,3 +69,121 @@ reviews: - "docs/design/transform/spdx-relationships.md" - "src/DemaConsulting.SpdxModel/Transform/SpdxRelationships.cs" - "test/DemaConsulting.SpdxModel.Tests/Transforms/SpdxRelationshipsTests.cs" + + - id: SpdxModel-SpdxAnnotation + title: SpdxModel SpdxAnnotation Unit Review + paths: + - "docs/reqstream/spdx-annotation.yaml" + - "docs/design/spdx-annotation.md" + - "src/DemaConsulting.SpdxModel/SpdxAnnotation.cs" + - "src/DemaConsulting.SpdxModel/SpdxAnnotationType.cs" + - "test/DemaConsulting.SpdxModel.Tests/SpdxAnnotationTests.cs" + + - id: SpdxModel-SpdxChecksum + title: SpdxModel SpdxChecksum Unit Review + paths: + - "docs/reqstream/spdx-checksum.yaml" + - "docs/design/spdx-checksum.md" + - "src/DemaConsulting.SpdxModel/SpdxChecksum.cs" + - "src/DemaConsulting.SpdxModel/SpdxChecksumAlgorithm.cs" + - "test/DemaConsulting.SpdxModel.Tests/SpdxChecksumTests.cs" + + - id: SpdxModel-SpdxCreationInformation + title: SpdxModel SpdxCreationInformation Unit Review + paths: + - "docs/reqstream/spdx-creation-information.yaml" + - "docs/design/spdx-creation-information.md" + - "src/DemaConsulting.SpdxModel/SpdxCreationInformation.cs" + - "test/DemaConsulting.SpdxModel.Tests/SpdxCreationInformationTests.cs" + + - id: SpdxModel-SpdxDocument + title: SpdxModel SpdxDocument Unit Review + paths: + - "docs/design/spdx-document.md" + - "src/DemaConsulting.SpdxModel/SpdxDocument.cs" + - "test/DemaConsulting.SpdxModel.Tests/SpdxDocumentTests.cs" + + - id: SpdxModel-SpdxElement + title: SpdxModel SpdxElement Unit Review + paths: + - "docs/design/spdx-element.md" + - "src/DemaConsulting.SpdxModel/SpdxElement.cs" + + - id: SpdxModel-SpdxExternalDocumentReference + title: SpdxModel SpdxExternalDocumentReference Unit Review + paths: + - "docs/reqstream/spdx-external-document-reference.yaml" + - "docs/design/spdx-external-document-reference.md" + - "src/DemaConsulting.SpdxModel/SpdxExternalDocumentReference.cs" + - "test/DemaConsulting.SpdxModel.Tests/SpdxExternalDocumentReferenceTests.cs" + + - id: SpdxModel-SpdxExternalReference + title: SpdxModel SpdxExternalReference Unit Review + paths: + - "docs/reqstream/spdx-external-reference.yaml" + - "docs/design/spdx-external-reference.md" + - "src/DemaConsulting.SpdxModel/SpdxExternalReference.cs" + - "src/DemaConsulting.SpdxModel/SpdxReferenceCategory.cs" + - "test/DemaConsulting.SpdxModel.Tests/SpdxExternalReferenceTests.cs" + + - id: SpdxModel-SpdxExtractedLicensingInfo + title: SpdxModel SpdxExtractedLicensingInfo Unit Review + paths: + - "docs/reqstream/spdx-extracted-licensing-info.yaml" + - "docs/design/spdx-extracted-licensing-info.md" + - "src/DemaConsulting.SpdxModel/SpdxExtractedLicensingInfo.cs" + - "test/DemaConsulting.SpdxModel.Tests/SpdxExtractedLicensingInfoTests.cs" + + - id: SpdxModel-SpdxFile + title: SpdxModel SpdxFile Unit Review + paths: + - "docs/reqstream/spdx-file.yaml" + - "docs/design/spdx-file.md" + - "src/DemaConsulting.SpdxModel/SpdxFile.cs" + - "src/DemaConsulting.SpdxModel/SpdxFileType.cs" + - "test/DemaConsulting.SpdxModel.Tests/SpdxFileTests.cs" + + - id: SpdxModel-SpdxHelpers + title: SpdxModel SpdxHelpers Unit Review + paths: + - "docs/design/spdx-helpers.md" + - "src/DemaConsulting.SpdxModel/SpdxHelpers.cs" + + - id: SpdxModel-SpdxLicenseElement + title: SpdxModel SpdxLicenseElement Unit Review + paths: + - "docs/design/spdx-license-element.md" + - "src/DemaConsulting.SpdxModel/SpdxLicenseElement.cs" + + - id: SpdxModel-SpdxPackage + title: SpdxModel SpdxPackage Unit Review + paths: + - "docs/reqstream/spdx-package.yaml" + - "docs/design/spdx-package.md" + - "src/DemaConsulting.SpdxModel/SpdxPackage.cs" + - "test/DemaConsulting.SpdxModel.Tests/SpdxPackageTests.cs" + + - id: SpdxModel-SpdxPackageVerificationCode + title: SpdxModel SpdxPackageVerificationCode Unit Review + paths: + - "docs/reqstream/spdx-package-verification-code.yaml" + - "docs/design/spdx-package-verification-code.md" + - "src/DemaConsulting.SpdxModel/SpdxPackageVerificationCode.cs" + - "test/DemaConsulting.SpdxModel.Tests/SpdxPackageVerificationCodeTests.cs" + + - id: SpdxModel-SpdxRelationship + title: SpdxModel SpdxRelationship Unit Review + paths: + - "docs/reqstream/spdx-relationship.yaml" + - "docs/design/spdx-relationship.md" + - "src/DemaConsulting.SpdxModel/SpdxRelationship.cs" + - "src/DemaConsulting.SpdxModel/SpdxRelationshipType.cs" + - "test/DemaConsulting.SpdxModel.Tests/SpdxRelationshipTests.cs" + + - id: SpdxModel-SpdxSnippet + title: SpdxModel SpdxSnippet Unit Review + paths: + - "docs/reqstream/spdx-snippet.yaml" + - "docs/design/spdx-snippet.md" + - "src/DemaConsulting.SpdxModel/SpdxSnippet.cs" + - "test/DemaConsulting.SpdxModel.Tests/SpdxSnippetTests.cs"