Skip to content

Commit 4ba3655

Browse files
CopilotMalcolmnixon
Copilot
and
Malcolmnixon
authored
Align repository structure with updated DEMA Consulting standards (#23)
* docs: restructure design and requirements files to comply with DEMA standards - 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> * Address PR review feedback on system.md and .reviewmark.yaml Agent-Logs-Url: https://github.com/demaconsulting/NuGetCaching/sessions/e5e94eae-08de-42b6-ba75-f5ccf093f18a Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> * Fix docs/design/definition.yaml to reference renamed design files Agent-Logs-Url: https://github.com/demaconsulting/NuGetCaching/sessions/db60e134-7b2f-4528-888d-4f960e9b3f11 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>
1 parent 4f2dda9 commit 4ba3655

19 files changed

Lines changed: 176 additions & 78 deletions

‎.reviewmark.yaml‎

Lines changed: 27 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,50 @@
11
---
22
# ReviewMark Configuration File
3-
# This file defines which files require review, where the evidence store is located,
4-
# and how files are grouped into named review-sets following software unit boundaries.
5-
6-
# Patterns identifying all files that require review.
7-
# Processed in order; prefix a pattern with '!' to exclude.
83
needs-review:
9-
- "**/*.cs" # All C# source and test files
10-
- "docs/design/**/*.md" # Design documents
4+
- "requirements.yaml" # Root requirements file
115
- "docs/reqstream/**/*.yaml" # Requirements files
6+
- "docs/design/**/*.md" # Design documents
7+
- "**/*.cs" # All C# source and test files
128
- "!**/obj/**" # Exclude build output
139
- "!**/bin/**" # Exclude build output
1410

15-
# Evidence source: review data and index.json are located in the 'reviews' branch
16-
# of this repository, accessed through the GitHub public HTTPS raw content access.
17-
# Note: The 'reviews' branch must be created and populated with review evidence PDFs
18-
# and an index.json before enforcement (--enforce flag) can be enabled in the pipeline.
1911
evidence-source:
2012
type: url
2113
location: https://raw.githubusercontent.com/demaconsulting/NuGetCaching/reviews/index.json
2214

23-
# Review sets grouping files by logical unit of review.
24-
# Each review-set groups requirements, source, and tests for a coherent software unit
25-
# so that an AI-assisted review can verify consistency across the full evidence chain.
2615
reviews:
27-
# Software unit reviews - one per class
16+
- id: NuGetCaching-System
17+
title: Review of NuGetCaching System Integration
18+
paths:
19+
- "docs/reqstream/system.yaml"
20+
- "docs/design/introduction.md"
21+
- "docs/design/system.md"
22+
23+
- id: NuGetCaching-Design
24+
title: Review of NuGetCaching Architecture and Design
25+
paths:
26+
- "docs/reqstream/system.yaml"
27+
- "docs/reqstream/platform-requirements.yaml"
28+
- "docs/design/**/*.md"
29+
30+
- id: NuGetCaching-AllRequirements
31+
title: Review of All NuGetCaching Requirements
32+
paths:
33+
- "requirements.yaml"
34+
- "docs/reqstream/**/*.yaml"
35+
2836
- id: NuGetCaching-NuGetCache
2937
title: Review of NuGetCaching NuGetCache Unit
3038
paths:
31-
- "docs/reqstream/unit-nuget-cache.yaml"
32-
- "docs/design/nuget-cache-design.md"
39+
- "docs/reqstream/nuget-cache.yaml"
40+
- "docs/design/nuget-cache.md"
3341
- "src/**/NuGetCache.cs"
3442
- "test/**/NuGetCacheTests.cs"
3543

3644
- id: NuGetCaching-PathHelpers
3745
title: Review of NuGetCaching PathHelpers Unit
3846
paths:
39-
- "docs/reqstream/unit-path-helpers.yaml"
40-
- "docs/design/path-helpers-design.md"
47+
- "docs/reqstream/path-helpers.yaml"
48+
- "docs/design/path-helpers.md"
4149
- "src/**/PathHelpers.cs"
4250
- "test/**/PathHelpersTests.cs"
43-
44-
# Platform and OTS dependency reviews
45-
- id: Platform-Support
46-
title: Review of Platform and Runtime Support Requirements
47-
paths:
48-
- "docs/reqstream/platform-requirements.yaml"
49-
50-
- id: OTS-Dependencies
51-
title: Review of Off-The-Shelf Software Dependencies
52-
paths:
53-
- "docs/reqstream/ots-mstest.yaml"
54-
- "docs/reqstream/ots-reqstream.yaml"
55-
- "docs/reqstream/ots-buildmark.yaml"
56-
- "docs/reqstream/ots-versionmark.yaml"
57-
- "docs/reqstream/ots-sarifmark.yaml"
58-
- "docs/reqstream/ots-sonarmark.yaml"
59-
- "docs/reqstream/ots-reviewmark.yaml"
60-
- "docs/reqstream/ots-nuget.yaml"

‎docs/design/definition.yaml‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,10 @@ resource-path:
44
- docs/template
55
input-files:
66
- docs/design/title.txt
7-
- docs/design/introduction.txt
8-
- docs/design/nuget-cache-design.md
9-
- docs/design/path-helpers-design.md
7+
- docs/design/introduction.md
8+
- docs/design/system.md
9+
- docs/design/nuget-cache.md
10+
- docs/design/path-helpers.md
1011
template: template.html
1112
table-of-contents: true
1213
number-sections: true

‎docs/design/introduction.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Introduction
2+
3+
## Purpose
4+
5+
This document provides the design documentation for the DemaConsulting NuGet Caching
6+
library. It serves as the bridge between requirements and implementation for formal
7+
code review and compliance auditing. Reviewers use this document to verify that the
8+
implementation matches the design, and auditors use it to trace requirements through
9+
design to code.
10+
11+
## Scope
12+
13+
This design documentation covers:
14+
15+
- The `NuGetCache` public static class providing package caching functionality
16+
- The `PathHelpers` internal static class providing safe path-combination utilities
17+
- Design decisions and rationale for each unit
18+
- Traceability from design to requirements
19+
20+
Excluded from scope:
21+
22+
- NuGet protocol internals and third-party library design
23+
- Build and packaging infrastructure
24+
- Platform-specific NuGet configuration details
25+
26+
## Software Structure
27+
28+
The software is organized as follows:
29+
30+
```text
31+
DemaConsulting.NuGet.Caching (System)
32+
├── NuGetCache (Unit)
33+
└── PathHelpers (Unit)
34+
```
35+
36+
## Folder Layout
37+
38+
The source code is organized to mirror the software structure:
39+
40+
```text
41+
src/DemaConsulting.NuGet.Caching/
42+
├── NuGetCache.cs — NuGet package caching class (public API)
43+
└── PathHelpers.cs — Safe path combination utilities (internal)
44+
```
45+
46+
Test code mirrors the source structure:
47+
48+
```text
49+
test/DemaConsulting.NuGet.Caching.Tests/
50+
├── NuGetCacheTests.cs — Tests for NuGetCache class
51+
└── PathHelpersTests.cs — Tests for PathHelpers class
52+
```
53+
54+
## Audience
55+
56+
This document is intended for:
57+
58+
- Software developers working on DemaConsulting NuGet Caching
59+
- Quality assurance teams validating design against requirements
60+
- Code reviewers assessing correctness and security of the implementation
61+
- Auditors verifying design traceability

‎docs/design/introduction.txt‎

Lines changed: 0 additions & 28 deletions
This file was deleted.

docs/design/nuget-cache-design.md renamed to docs/design/nuget-cache.md

File renamed without changes.

docs/design/path-helpers-design.md renamed to docs/design/path-helpers.md

File renamed without changes.

‎docs/design/system.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# System Design
2+
3+
## Overview
4+
5+
The DemaConsulting NuGet Caching library is a .NET library that provides programmatic
6+
NuGet package caching functionality. The system ensures specific NuGet package versions
7+
are available in the local global packages cache before use, enabling tools and automation
8+
workflows to depend on locally cached packages without requiring the .NET SDK restore
9+
workflow.
10+
11+
## System Architecture
12+
13+
The system comprises two software units:
14+
15+
- **NuGetCache**: The public API surface providing the `EnsureCachedAsync` method
16+
- **PathHelpers**: An internal utility class providing safe path-combination operations
17+
18+
## External Interfaces
19+
20+
### NuGet Protocol (NuGet.Protocol)
21+
22+
The system communicates with NuGet package sources using the NuGet client SDK
23+
(`NuGet.Protocol`). This provides:
24+
25+
- `SourceRepository` for connecting to NuGet v2 and v3 feeds
26+
- `FindPackageByIdResource` for locating and downloading packages
27+
- `GlobalPackagesFolderUtility` for installing packages into the global cache
28+
29+
### NuGet Configuration (NuGet.Configuration)
30+
31+
The system reads NuGet configuration from the local machine using `NuGet.Configuration`.
32+
This provides:
33+
34+
- `Settings.LoadDefaultSettings` for reading the NuGet configuration hierarchy
35+
- `SettingsUtility.GetGlobalPackagesFolder` for resolving the cache directory
36+
- `PackageSourceProvider` for enumerating enabled package sources
37+
- `PackageSourceMapping` for respecting package source mapping rules
38+
39+
## Data Flow
40+
41+
1. Caller invokes `NuGetCache.EnsureCachedAsync(packageId, version)`
42+
2. The system loads NuGet configuration from machine/user settings
43+
3. The system checks for a cached package using the sentinel file (`.nupkg.metadata`)
44+
4. If not cached, the system queries configured NuGet sources sequentially
45+
5. On successful download, the package is installed into the global packages folder
46+
6. The absolute path to the cached package folder is returned
47+
48+
## Design Constraints
49+
50+
- The library targets .NET Standard 2.0 for maximum compatibility, with additional
51+
security validation enabled on .NET 5.0 and later
52+
- The system reads from the same NuGet configuration hierarchy as the `dotnet` CLI
53+
and Visual Studio, ensuring consistent behavior
54+
- All path operations use `PathHelpers.SafePathCombine` to prevent path traversal
55+
vulnerabilities when processing package identifiers and version strings from
56+
external NuGet feeds

docs/reqstream/unit-nuget-cache.yaml renamed to docs/reqstream/nuget-cache.yaml

File renamed without changes.

docs/reqstream/ots-buildmark.yaml renamed to docs/reqstream/ots/buildmark.yaml

File renamed without changes.

docs/reqstream/ots-mstest.yaml renamed to docs/reqstream/ots/mstest.yaml

File renamed without changes.

0 commit comments

Comments
 (0)