-
Notifications
You must be signed in to change notification settings - Fork 0
Add design docs, split requirements by subsystem and unit, expand ReviewMark coverage #136
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Malcolmnixon
merged 8 commits into
main
from
copilot/update-repository-to-comply-standards
Apr 3, 2026
Merged
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
a5d4e0a
Add design docs, split requirements into subsystem files, update revi…
Copilot ab3e275
Add unit-level design docs and split unit requirements into individua…
Copilot a809af3
Split IO and Transform subsystem requirements into unit-level files
Copilot c5480e3
Update docs/design/io/io.md
Malcolmnixon e349683
Update docs/design/system.md
Malcolmnixon 9a56a12
Update docs/design/system.md
Malcolmnixon f060ce0
Fix design doc inaccuracies: SpdxHelpers regex/EnhanceString, Transfo…
Copilot 09f5bb5
Fix .reviewmark.yaml: slim System review-set, add 15 unit review-sets
Copilot File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -59,6 +59,7 @@ words: | |
| - mstest | ||
| - myterm | ||
| - nameof | ||
| - netstandard | ||
| - ncipollo | ||
| - Neko | ||
| - NOASSERTION | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
| # 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.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 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`, 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: | ||
|
|
||
| - 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.) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.