Apply subsystem folder structure to SarifMark (mirrors TemplateDotNetTool PR #81) by Copilot · Pull Request #84 · demaconsulting/SarifMark

Copilot · 2026-03-31T17:44:08Z

Reorganizes source, tests, design docs, and requirements into subsystem subdirectories matching the software hierarchy, following the pattern established in TemplateDotNetTool PR #81.

Description

SarifMark (System)
├── Program (Unit)
├── Cli (Subsystem)        → Context
├── Sarif (Subsystem)      → SarifResult, SarifResults
├── SelfTest (Subsystem)   → Validation
└── Utilities (Subsystem)  → PathHelpers

Source & Tests

Moved Context.cs → Cli/, SarifResult.cs + SarifResults.cs → Sarif/, Validation.cs → SelfTest/, PathHelpers.cs → Utilities/ (namespaces unchanged)
Mirrored the same layout for all test files

Design Docs (`docs/design/`)

Added docs/design/system.md — system-level design document describing overall architecture, subsystem table, entry point execution flow, and a Mermaid flowchart showing subsystem interactions
Moved unit design docs into subsystem subdirectories
Added subsystem-level design docs: cli/cli.md, self-test/self-test.md, utilities/utilities.md; moved sarif.md → sarif/sarif.md
Added Software Structure and Folder Layout sections to introduction.md
Updated definition.yaml with new resource-path entries and input-files paths (including system.md)

Requirements (`docs/reqstream/`)

Renamed all unit requirements to follow unit-{unit}.yaml convention: unit-context.yaml, unit-sarif-result.yaml, unit-sarif-results.yaml, unit-validation.yaml, unit-path-helpers.yaml, unit-program.yaml
Renamed platform.yaml → platform-requirements.yaml
Moved unit and subsystem requirements into subsystem subdirectories: cli/, sarif/, self-test/, utilities/
Added sarifmark-system.yaml — 9 system-level requirements linked to integration tests
Added utilities/subsystem-utilities.yaml
Updated requirements.yaml includes
Fixed all children: links to go strictly "down" in the software hierarchy (subsystem → unit within that subsystem); removed cross-subsystem references to Program-* and Context-* units from Sarif/SelfTest/Report subsystem requirements; replaced non-existent SarifMark-PathHelpers-TraversalCheck with PreCombineCheck, RootedCheck, and PostCombineCheck; corrected two non-existent test method names in sarifmark-system.yaml (IntegrationTest_SarifFile_ProcessesSarifFile → IntegrationTest_ValidSarifFile_ProcessesSuccessfully, IntegrationTest_ReportFile_GeneratesMarkdownReport → IntegrationTest_GenerateReport_CreatesReportFile)

`.reviewmark.yaml`

Added requirements.yaml to needs-review
Renamed all review sets to [Product]-[Name] convention (e.g. SarifMark-Cli, SarifMark-Sarif, SarifMark-Context, SarifMark-PathHelpers)
Added SarifMark-System (includes platform-requirements.yaml, ots-software.yaml, system.md, integration tests), SarifMark-AllRequirements, and SarifMark-Utilities review sets
Removed SarifMark-Platform-Subsystem-Review — Platform is not a subsystem; platform and OTS files are now covered under SarifMark-System
Updated all file paths across existing review sets

`AGENTS.md`

Added design/ folder entry documenting introduction.md as the System/Subsystem/Unit breakdown reference

Type of Change

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Documentation update
Code quality improvement

Related Issues

Pre-Submission Checklist

Build and Test

Code builds successfully: dotnet build --configuration Release
All unit tests pass: dotnet test --configuration Release
Self-validation tests pass:
dotnet run --project src/DemaConsulting.SarifMark --configuration Release --framework net10.0
--no-build -- --validate
Code produces zero warnings

Code Quality

Code formatting is correct: dotnet format --verify-no-changes
New code has appropriate XML documentation comments
Static analyzer warnings have been addressed

Quality Checks

All linters pass: ./lint.sh (Unix/macOS) or cmd /c lint.bat / ./lint.bat (Windows)

Testing

Added unit tests for new functionality
Updated existing tests if behavior changed
All tests follow the AAA (Arrange, Act, Assert) pattern
Test coverage is maintained or improved

Documentation

Updated README.md (if applicable)
Updated ARCHITECTURE.md (if applicable)
Added code examples for new features (if applicable)
Updated requirements.yaml (if applicable)

Additional Notes

No functional or behavioral changes — this is a pure structural reorganization. All 303 tests pass (101 × net8/net9/net10). CodeQL: 0 alerts. All 102 requirements are satisfied with tests.

Agent-Logs-Url: https://github.com/demaconsulting/SarifMark/sessions/de046716-8a2b-4854-8520-1cdeff41c086 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

Malcolmnixon · 2026-03-31T18:40:30Z

@copilot There are a few issues:

I'm not seeing a docs/design/system.md with information about the software-system.
The docs/reqstream files don't seem to follow the naming convention (read the .github/standards/reqstream-usage.md)
The 'SarifMark-Platform-Subsystem-Review' is odd as Platform is not a subsystem
The review-set names don't match the convention (read the .github/standards/reviewmark-usage.md)

…view-set names Agent-Logs-Url: https://github.com/demaconsulting/SarifMark/sessions/5124cd09-8a76-4644-84e1-025cbe9a7967 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

Copilot · 2026-03-31T18:55:39Z

@copilot There are a few issues:

I'm not seeing a docs/design/system.md with information about the software-system.

The docs/reqstream files don't seem to follow the naming convention (read the ...

Addressed in commit 9c2db46:

docs/design/system.md — added, describing the system overview, subsystem table, entry point execution flow, and subsystem interaction diagram.
Reqstream naming convention — renamed all unit files to unit-{unit}.yaml (unit-context.yaml, unit-sarif-result.yaml, unit-sarif-results.yaml, unit-validation.yaml, unit-path-helpers.yaml, unit-program.yaml) and platform.yaml → platform-requirements.yaml.
Platform review — removed SarifMark-Platform-Subsystem-Review; platform-requirements.yaml and ots-software.yaml are now covered under SarifMark-System.
Review-set names — renamed all sets to the [Product]-[Name] convention (e.g. SarifMark-Cli, SarifMark-Sarif, SarifMark-Context, SarifMark-PathHelpers, etc.).

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

https://storage.googleapis.com/chromium-browser-snapshots/Linux_x64/1108766/chrome-linux.zip
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node install.js (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

docs/design/system.md

Agent-Logs-Url: https://github.com/demaconsulting/SarifMark/sessions/c0ec5818-3858-4c7c-b314-bdabee8c681e Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

Copilot · 2026-03-31T19:04:42Z

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

https://storage.googleapis.com/chromium-browser-snapshots/Linux_x64/1108766/chrome-linux.zip
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node install.js (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Copilot

Pull request overview

This PR aligns SarifMark with a subsystem-oriented structure (mirroring TemplateDotNetTool PR #81), reorganizing source/tests/docs/requirements into consistent subsystem folders and adding system/subsystem design + requirements artifacts to support traceability and ReviewMark review sets.

Changes:

Reorganize src/ and test/ into subsystem folders (Cli/Sarif/SelfTest/Utilities) and update supporting test suites accordingly.
Restructure docs/design/ and docs/reqstream/ into subsystem/system documents and update root requirements.yaml includes.
Update .reviewmark.yaml review sets and paths to reflect the new system/subsystem/unit breakdown.

Reviewed changes

Copilot reviewed 12 out of 38 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
test/DemaConsulting.SarifMark.Tests/Utilities/PathHelpersTests.cs	Adds/relocates PathHelpers unit tests under Utilities.
test/DemaConsulting.SarifMark.Tests/SelfTest/ValidationTests.cs	Adds/relocates self-validation unit tests under SelfTest.
test/DemaConsulting.SarifMark.Tests/Sarif/SarifResultsTests.cs	Adds/relocates SARIF parsing/reporting unit tests under Sarif.
test/DemaConsulting.SarifMark.Tests/Cli/ContextTests.cs	Adds/relocates CLI Context unit tests under Cli.
src/DemaConsulting.SarifMark/Utilities/PathHelpers.cs	Introduces/relocates safe path-combination utility.
src/DemaConsulting.SarifMark/SelfTest/Validation.cs	Introduces/relocates self-validation runner and results output.
src/DemaConsulting.SarifMark/Sarif/SarifResults.cs	Introduces/relocates SARIF reader + markdown formatter.
src/DemaConsulting.SarifMark/Sarif/SarifResult.cs	Introduces/relocates SARIF result record type.
src/DemaConsulting.SarifMark/Cli/Context.cs	Introduces/relocates CLI argument parsing/output routing context.
requirements.yaml	Updates root includes to new reqstream file layout.
docs/reqstream/utilities/unit-path-helpers.yaml	Adds Utilities unit requirements for PathHelpers.
docs/reqstream/utilities/subsystem-utilities.yaml	Adds Utilities subsystem-level requirements.
docs/reqstream/unit-program.yaml	Adds Program unit-level requirements under new naming/layout.
docs/reqstream/self-test/unit-validation.yaml	Adds Validation unit requirements under SelfTest.
docs/reqstream/self-test/subsystem-self-test.yaml	Adds SelfTest subsystem requirements (validation/enforcement).
docs/reqstream/sarifmark-system.yaml	Adds system-level requirements and links to integration tests.
docs/reqstream/sarif/unit-sarif-results.yaml	Adds SarifResults unit requirements and traceability to tests.
docs/reqstream/sarif/unit-sarif-result.yaml	Adds SarifResult unit requirements and traceability to tests.
docs/reqstream/sarif/subsystem-sarif.yaml	Adds SARIF subsystem requirements.
docs/reqstream/sarif/subsystem-report.yaml	Adds report-generation subsystem requirements.
docs/reqstream/platform-requirements.yaml	Adds platform/runtime requirements with evidence filters.
docs/reqstream/cli/unit-context.yaml	Adds Context unit requirements and test traceability.
docs/reqstream/cli/subsystem-cli.yaml	Adds CLI subsystem requirements and test traceability.
docs/design/utilities/utilities.md	Adds Utilities subsystem design doc.
docs/design/utilities/path-helpers.md	Adds PathHelpers unit design doc.
docs/design/system.md	Adds system-level design doc + Mermaid interaction diagram.
docs/design/self-test/validation.md	Adds Validation unit design doc.
docs/design/self-test/self-test.md	Adds SelfTest subsystem design doc.
docs/design/sarif/sarif.md	Adds Sarif subsystem design doc.
docs/design/sarif/sarif-results.md	Adds SarifResults unit design doc.
docs/design/sarif/sarif-result.md	Adds SarifResult unit design doc.
docs/design/introduction.md	Updates introduction with software structure + folder layout.
docs/design/definition.yaml	Updates doc build definition with new inputs/paths.
docs/design/command-line.md	Removes legacy monolithic CLI design doc (replaced by subsystem docs).
docs/design/cli/context.md	Adds CLI Context unit design doc.
docs/design/cli/cli.md	Adds CLI subsystem design doc.
AGENTS.md	Updates project structure documentation to include `docs/design/`.
.reviewmark.yaml	Updates review sets and paths for system/subsystem/unit structure.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/reqstream/utilities/subsystem-utilities.yaml

docs/reqstream/sarifmark-system.yaml

Malcolmnixon · 2026-03-31T19:15:07Z

@copilot Some of the requirement "children" links are broken (referring to requirement IDs that don't exist). Please review all requirements and their linking, and make sure:

children links go "down" in the software structure
children links go to relevant child requirement IDs.

Malcolmnixon · 2026-03-31T19:20:45Z

@copilot The CI build failed with:

Error: Only 100 of 102 requirements are satisfied with tests.
Unsatisfied requirements:
  - SarifMark-System-SarifAnalysis
  - SarifMark-System-Report

Agent-Logs-Url: https://github.com/demaconsulting/SarifMark/sessions/3af2c08c-35a2-4ee4-a57a-94ed9b6ff2ad Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

Copilot · 2026-03-31T19:30:37Z

@copilot Some of the requirement "children" links are broken (referring to requirement IDs that don't exist). Please review all requirements and their linking, and make sure:

children links go "dow...

Fixed in commit c25e81f. All children links now go strictly "down" within the software structure (subsystem → unit within that subsystem):

sarifmark-system.yaml: fixed 2 non-existent test names (IntegrationTest_SarifFile_ProcessesSarifFile → IntegrationTest_ValidSarifFile_ProcessesSuccessfully, IntegrationTest_ReportFile_GeneratesMarkdownReport → IntegrationTest_GenerateReport_CreatesReportFile)
subsystem-utilities.yaml: replaced non-existent SarifMark-PathHelpers-TraversalCheck with the three actual traversal-check requirements (PreCombineCheck, RootedCheck, PostCombineCheck)
subsystem-cli.yaml: removed Program-Main, Program-Version, Program-Banner, Program-Help, Program-Main-Exceptions — children now only reference Context unit requirements within the Cli subsystem
subsystem-sarif.yaml: replaced Program-SarifAnalysis with SarifResults unit requirements within the Sarif subsystem
subsystem-report.yaml: removed Context-ReportDepthParam and Context-HeadingParam (Cli unit) — children now only reference SarifResults unit requirements
subsystem-self-test.yaml: replaced Context-* (Cli) and Program-* cross-subsystem children with Validation-EnforcementTest (within the SelfTest subsystem)

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

https://storage.googleapis.com/chromium-browser-snapshots/Linux_x64/1108766/chrome-linux.zip
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node install.js (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Copilot · 2026-03-31T19:38:41Z

@copilot The CI build failed with:
Error: Only 100 of 102 requirements are satisfied with tests.

...

This was already fixed in commit c25e81f. That commit corrected the two broken test names in sarifmark-system.yaml:

IntegrationTest_SarifFile_ProcessesSarifFile → IntegrationTest_ValidSarifFile_ProcessesSuccessfully
IntegrationTest_ReportFile_GeneratesMarkdownReport → IntegrationTest_GenerateReport_CreatesReportFile

I've confirmed locally with reqstream that neither SarifMark-System-SarifAnalysis nor SarifMark-System-Report appear in the unsatisfied list any longer.

Copilot

Pull request overview

Copilot reviewed 16 out of 38 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (3)

docs/reqstream/sarif/subsystem-sarif.yaml:97

SarifMark-Sarif-Required is about requiring the --sarif CLI parameter, but its children link points to SarifMark-SarifResults-ValidatePath, which only validates the file path once provided. The actual enforcement of a missing --sarif parameter occurs in Program.ProcessSarifAnalysis (and is covered by SarifMark-Program-SarifAnalysis). Consider updating the child link (or relocating this requirement to the CLI/system level) so the hierarchy reflects where the behavior is implemented.
docs/reqstream/sarif/subsystem-report.yaml:27
For SarifMark-Report-Depth, the children link now points only to SarifMark-SarifResults-ValidateDepth, which validates the numeric range but doesn’t cover how the depth is made configurable via --report-depth (implemented in Context / SarifMark-Context-ReportDepthParam). Please consider linking to the CLI/unit requirement as well (or moving this requirement to the CLI subsystem) so the trace matches the end-to-end behavior.
docs/reqstream/sarif/subsystem-report.yaml:62
For SarifMark-Report-Headings, the hierarchy only references SarifMark-SarifResults-ToMarkdown but the configurability is also provided by the --heading CLI parameter (implemented in Context / SarifMark-Context-HeadingParam). Consider linking that unit requirement (or moving this requirement to the CLI subsystem) to keep the requirement-to-implementation trace accurate.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/design/system.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Initial plan

ee52fb0

Copilot AI assigned Copilot and Malcolmnixon Mar 31, 2026

Copilot started work on behalf of Malcolmnixon March 31, 2026 17:44 View session

Copilot AI changed the title ~~[WIP] Update folder structures and documentation format~~ Apply subsystem folder structure to SarifMark (mirrors TemplateDotNetTool PR #81) Mar 31, 2026

Copilot finished work on behalf of Malcolmnixon March 31, 2026 18:14

Copilot AI requested a review from Malcolmnixon March 31, 2026 18:14

Copilot started work on behalf of Malcolmnixon March 31, 2026 18:40 View session

Malcolmnixon requested changes Mar 31, 2026

View reviewed changes

docs/design/system.md Outdated Show resolved Hide resolved

Copilot AI requested a review from Malcolmnixon March 31, 2026 18:58

Copilot finished work on behalf of Malcolmnixon March 31, 2026 18:58

Copilot started work on behalf of Malcolmnixon March 31, 2026 18:58 View session

Convert system.md ASCII art diagram to Mermaid flowchart

aa6a36a

Agent-Logs-Url: https://github.com/demaconsulting/SarifMark/sessions/c0ec5818-3858-4c7c-b314-bdabee8c681e Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

Malcolmnixon marked this pull request as ready for review March 31, 2026 19:04

Copilot AI review requested due to automatic review settings March 31, 2026 19:04

Copilot started reviewing on behalf of Malcolmnixon March 31, 2026 19:04 View session

Copilot finished work on behalf of Malcolmnixon March 31, 2026 19:04

Malcolmnixon approved these changes Mar 31, 2026

View reviewed changes

Copilot AI reviewed Mar 31, 2026

View reviewed changes

docs/reqstream/utilities/subsystem-utilities.yaml Outdated Show resolved Hide resolved

docs/reqstream/sarifmark-system.yaml Outdated Show resolved Hide resolved

docs/reqstream/sarifmark-system.yaml Outdated Show resolved Hide resolved

Copilot started work on behalf of Malcolmnixon March 31, 2026 19:15 View session

Fix broken children links in reqstream requirements files

c25e81f

Agent-Logs-Url: https://github.com/demaconsulting/SarifMark/sessions/3af2c08c-35a2-4ee4-a57a-94ed9b6ff2ad Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

Copilot finished work on behalf of Malcolmnixon March 31, 2026 19:31

Copilot AI requested a review from Malcolmnixon March 31, 2026 19:31

Copilot started work on behalf of Malcolmnixon March 31, 2026 19:31 View session

Copilot finished work on behalf of Malcolmnixon March 31, 2026 19:39

Malcolmnixon requested a review from Copilot March 31, 2026 19:55

Copilot started reviewing on behalf of Malcolmnixon March 31, 2026 19:55 View session

Copilot AI reviewed Mar 31, 2026

View reviewed changes

docs/design/system.md Outdated Show resolved Hide resolved

docs/design/system.md Outdated Show resolved Hide resolved

Malcolmnixon and others added 2 commits March 31, 2026 16:06

Update docs/design/system.md

4ca61f3

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/design/system.md

3dd6920

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Malcolmnixon merged commit c344d4b into main Mar 31, 2026
15 checks passed

Malcolmnixon deleted the copilot/update-folder-structure branch March 31, 2026 20:17

Conversation

Copilot AI commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Source & Tests

Design Docs (docs/design/)

Requirements (docs/reqstream/)

.reviewmark.yaml

AGENTS.md

Type of Change

Related Issues

Pre-Submission Checklist

Build and Test

Code Quality

Quality Checks

Testing

Documentation

Additional Notes

Uh oh!

Malcolmnixon commented Mar 31, 2026

Uh oh!

Copilot AI commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Uh oh!

Copilot AI commented Mar 31, 2026

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Malcolmnixon commented Mar 31, 2026

Uh oh!

Malcolmnixon commented Mar 31, 2026

Uh oh!

Copilot AI commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Copilot AI commented Mar 31, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Mar 31, 2026 •

edited

Loading

Design Docs (`docs/design/`)

Requirements (`docs/reqstream/`)

`.reviewmark.yaml`

`AGENTS.md`

Copilot AI commented Mar 31, 2026 •

edited

Loading

Copilot AI commented Mar 31, 2026 •

edited

Loading