Align repository structure with updated DEMA Consulting standards #23
Next
Next commit
docs: restructure design and requirements files to comply with DEMA s…
…tandards - Delete docs/design/introduction.txt and create docs/design/introduction.md with required Software Structure and Folder Layout sections - Create docs/design/system.md with system architecture, external interfaces, data flow, and design constraints - Rename docs/design/nuget-cache-design.md -> docs/design/nuget-cache.md - Rename docs/design/path-helpers-design.md -> docs/design/path-helpers.md - Create docs/reqstream/system.yaml with system-level requirements - Rename docs/reqstream/unit-nuget-cache.yaml -> docs/reqstream/nuget-cache.yaml - Rename docs/reqstream/unit-path-helpers.yaml -> docs/reqstream/path-helpers.yaml - Move all OTS reqstream files into docs/reqstream/ots/ subdirectory - Update requirements.yaml includes to use new file paths - Update .reviewmark.yaml with standard review-sets including system-level reviews and requirements.yaml in needs-review Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>
- Loading branch information
commit 9e29d66fb2192426d4ff9fd65e41ff241b045c91
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 |
|---|---|---|
| @@ -1,60 +1,63 @@ | ||
| --- | ||
| # ReviewMark Configuration File | ||
| needs-review: | ||
| - "requirements.yaml" # Root requirements file | ||
| - "docs/reqstream/**/*.yaml" # Requirements files | ||
| - "docs/design/**/*.md" # Design documents | ||
| - "**/*.cs" # All C# source and test files | ||
| - "!**/obj/**" # Exclude build output | ||
| - "!**/bin/**" # Exclude build output | ||
|
|
||
| evidence-source: | ||
| type: url | ||
| location: https://raw.githubusercontent.com/demaconsulting/NuGetCaching/reviews/index.json | ||
|
|
||
| reviews: | ||
| - id: NuGetCaching-System | ||
| title: Review of NuGetCaching System Integration | ||
| paths: | ||
| - "docs/reqstream/system.yaml" | ||
| - "docs/design/introduction.md" | ||
| - "docs/design/system.md" | ||
|
|
||
| - id: NuGetCaching-Design | ||
| title: Review of NuGetCaching Architecture and Design | ||
| paths: | ||
| - "docs/reqstream/system.yaml" | ||
| - "docs/reqstream/platform-requirements.yaml" | ||
| - "docs/design/introduction.md" | ||
| - "docs/design/system.md" | ||
| - "docs/design/nuget-cache.md" | ||
| - "docs/design/path-helpers.md" | ||
|
|
||
| - id: NuGetCaching-AllRequirements | ||
| title: Review of All NuGetCaching Requirements | ||
| paths: | ||
| - "requirements.yaml" | ||
| - "docs/reqstream/**/*.yaml" | ||
|
|
||
| - id: NuGetCaching-NuGetCache | ||
| title: Review of NuGetCaching NuGetCache Unit | ||
| paths: | ||
| - "docs/reqstream/nuget-cache.yaml" | ||
| - "docs/design/nuget-cache.md" | ||
| - "src/**/NuGetCache.cs" | ||
| - "test/**/NuGetCacheTests.cs" | ||
|
|
||
| - id: NuGetCaching-PathHelpers | ||
| title: Review of NuGetCaching PathHelpers Unit | ||
| paths: | ||
| - "docs/reqstream/path-helpers.yaml" | ||
| - "docs/design/path-helpers.md" | ||
| - "src/**/PathHelpers.cs" | ||
| - "test/**/PathHelpersTests.cs" | ||
|
|
||
| - id: NuGetCaching-OTS | ||
|
Malcolmnixon marked this conversation as resolved.
Outdated
|
||
| title: Review of NuGetCaching Off-The-Shelf Dependencies | ||
| paths: | ||
| - "docs/reqstream/ots/**/*.yaml" | ||
|
|
||
| - id: NuGetCaching-Platform | ||
|
Malcolmnixon marked this conversation as resolved.
Outdated
|
||
| title: Review of NuGetCaching Platform Support Requirements | ||
| paths: | ||
| - "docs/reqstream/platform-requirements.yaml" | ||
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,61 @@ | ||
| # Introduction | ||
|
|
||
| ## Purpose | ||
|
|
||
| This document provides the design documentation for the DemaConsulting NuGet Caching | ||
|
Malcolmnixon marked this conversation as resolved.
|
||
| library. It serves as the bridge between requirements and implementation for formal | ||
| code review and compliance auditing. Reviewers use this document to verify that the | ||
| implementation matches the design, and auditors use it to trace requirements through | ||
| design to code. | ||
|
|
||
| ## Scope | ||
|
|
||
| This design documentation covers: | ||
|
|
||
| - The `NuGetCache` public static class providing package caching functionality | ||
| - The `PathHelpers` internal static class providing safe path-combination utilities | ||
| - Design decisions and rationale for each unit | ||
| - Traceability from design to requirements | ||
|
|
||
| Excluded from scope: | ||
|
|
||
| - NuGet protocol internals and third-party library design | ||
| - Build and packaging infrastructure | ||
| - Platform-specific NuGet configuration details | ||
|
|
||
| ## Software Structure | ||
|
|
||
| The software is organized as follows: | ||
|
|
||
| ```text | ||
| DemaConsulting.NuGet.Caching (System) | ||
| ├── NuGetCache (Unit) | ||
| └── PathHelpers (Unit) | ||
| ``` | ||
|
|
||
| ## Folder Layout | ||
|
|
||
| The source code is organized to mirror the software structure: | ||
|
|
||
| ```text | ||
| src/DemaConsulting.NuGet.Caching/ | ||
| ├── NuGetCache.cs — NuGet package caching class (public API) | ||
| └── PathHelpers.cs — Safe path combination utilities (internal) | ||
| ``` | ||
|
|
||
| Test code mirrors the source structure: | ||
|
|
||
| ```text | ||
| test/DemaConsulting.NuGet.Caching.Tests/ | ||
| ├── NuGetCacheTests.cs — Tests for NuGetCache class | ||
| └── PathHelpersTests.cs — Tests for PathHelpers class | ||
| ``` | ||
|
|
||
| ## Audience | ||
|
|
||
| This document is intended for: | ||
|
|
||
| - Software developers working on DemaConsulting NuGet Caching | ||
| - Quality assurance teams validating design against requirements | ||
| - Code reviewers assessing correctness and security of the implementation | ||
| - Auditors verifying design traceability | ||
File renamed without changes.
File renamed without changes.
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,56 @@ | ||
| # System Design | ||
|
|
||
| ## Overview | ||
|
|
||
| The DemaConsulting NuGet Caching library is a .NET library that provides programmatic | ||
| NuGet package caching functionality. The system ensures specific NuGet package versions | ||
| are available in the local global packages cache before use, enabling tools and automation | ||
| workflows to depend on locally cached packages without requiring the .NET SDK restore | ||
| workflow. | ||
|
|
||
| ## System Architecture | ||
|
|
||
| The system comprises two software units: | ||
|
|
||
| - **NuGetCache**: The public API surface providing the `EnsureCachedAsync` method | ||
| - **PathHelpers**: An internal utility class providing safe path-combination operations | ||
|
|
||
| ## External Interfaces | ||
|
|
||
| ### NuGet Protocol (NuGet.Protocol) | ||
|
|
||
| The system communicates with NuGet package sources using the NuGet client SDK | ||
| (`NuGet.Protocol` version 7.3.0). This provides: | ||
|
Malcolmnixon marked this conversation as resolved.
Outdated
|
||
|
|
||
| - `SourceRepository` for connecting to NuGet v2 and v3 feeds | ||
| - `FindPackageByIdResource` for locating and downloading packages | ||
| - `GlobalPackagesFolderUtility` for installing packages into the global cache | ||
|
|
||
| ### NuGet Configuration (NuGet.Configuration) | ||
|
|
||
| The system reads NuGet configuration from the local machine using `NuGet.Configuration` | ||
| version 7.3.0. This provides: | ||
|
Malcolmnixon marked this conversation as resolved.
Outdated
|
||
|
|
||
| - `Settings.LoadDefaultSettings` for reading the NuGet configuration hierarchy | ||
| - `SettingsUtility.GetGlobalPackagesFolder` for resolving the cache directory | ||
| - `PackageSourceProvider` for enumerating enabled package sources | ||
| - `PackageSourceMapping` for respecting package source mapping rules | ||
|
|
||
| ## Data Flow | ||
|
|
||
| 1. Caller invokes `NuGetCache.EnsureCachedAsync(packageId, version)` | ||
| 2. The system loads NuGet configuration from machine/user settings | ||
| 3. The system checks for a cached package using the sentinel file (`.nupkg.metadata`) | ||
| 4. If not cached, the system queries configured NuGet sources sequentially | ||
| 5. On successful download, the package is installed into the global packages folder | ||
| 6. The absolute path to the cached package folder is returned | ||
|
|
||
| ## Design Constraints | ||
|
|
||
| - The library targets .NET Standard 2.0 for maximum compatibility, with additional | ||
| security validation enabled on .NET 5.0 and later | ||
| - The system reads from the same NuGet configuration hierarchy as the `dotnet` CLI | ||
| and Visual Studio, ensuring consistent behavior | ||
| - All path operations use `PathHelpers.SafePathCombine` to prevent path traversal | ||
| vulnerabilities when processing package identifiers and version strings from | ||
| external NuGet feeds | ||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
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,17 @@ | ||
| --- | ||
| # System-Level Requirements for the NuGetCaching Library | ||
| # | ||
| # These requirements define the overall system behavior and integration | ||
| # requirements for the DemaConsulting NuGet Caching library. | ||
|
|
||
| sections: | ||
| - title: System Requirements | ||
| requirements: | ||
| - id: Caching-Sys-PackageCaching | ||
| title: The system shall provide a .NET library for programmatic NuGet package caching. | ||
| justification: | | ||
| Tools and automation workflows need to ensure specific NuGet package versions are | ||
| available in the local global packages cache before use, without requiring the | ||
| full .NET SDK restore workflow. | ||
| tests: | ||
| - NuGetCache_EnsureCachedAsync_ReturnsPackageFolder |
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
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.