From ee52fb0f14914fc8a3314240fcee1defed2c7820 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 17:44:07 +0000 Subject: [PATCH 1/7] Initial plan From fc9963f4349ed800b6417a6c78014858f14681ea Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 18:13:02 +0000 Subject: [PATCH 2/7] Apply TemplateDotNetTool PR #81 subsystem folder structure to SarifMark Agent-Logs-Url: https://github.com/demaconsulting/SarifMark/sessions/de046716-8a2b-4854-8520-1cdeff41c086 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .reviewmark.yaml | 127 ++++++++++-------- AGENTS.md | 2 + docs/design/cli/cli.md | 41 ++++++ docs/design/{ => cli}/context.md | 0 docs/design/command-line.md | 52 ------- docs/design/definition.yaml | 20 ++- docs/design/introduction.md | 42 ++++++ docs/design/{ => sarif}/sarif-result.md | 0 docs/design/{ => sarif}/sarif-results.md | 0 docs/design/{ => sarif}/sarif.md | 0 docs/design/self-test/self-test.md | 39 ++++++ docs/design/{ => self-test}/validation.md | 0 docs/design/{ => utilities}/path-helpers.md | 0 docs/design/utilities/utilities.md | 36 +++++ docs/reqstream/{ => cli}/context.yaml | 0 .../subsystem-cli.yaml} | 0 docs/reqstream/{ => sarif}/sarif-result.yaml | 0 docs/reqstream/{ => sarif}/sarif-results.yaml | 0 .../subsystem-report.yaml} | 0 .../subsystem-sarif.yaml} | 0 docs/reqstream/sarifmark-system.yaml | 79 +++++++++++ .../subsystem-self-test.yaml} | 0 .../{ => self-test}/validation-class.yaml | 0 .../{ => utilities}/path-helpers.yaml | 0 .../utilities/subsystem-utilities.yaml | 18 +++ requirements.yaml | 20 +-- .../{ => Cli}/Context.cs | 0 .../{ => Sarif}/SarifResult.cs | 0 .../{ => Sarif}/SarifResults.cs | 0 .../{ => SelfTest}/Validation.cs | 0 .../{ => Utilities}/PathHelpers.cs | 0 .../{ => Cli}/ContextTests.cs | 0 .../{ => Sarif}/SarifResultsTests.cs | 0 .../{ => SelfTest}/ValidationTests.cs | 0 .../{ => Utilities}/PathHelpersTests.cs | 0 35 files changed, 349 insertions(+), 127 deletions(-) create mode 100644 docs/design/cli/cli.md rename docs/design/{ => cli}/context.md (100%) delete mode 100644 docs/design/command-line.md rename docs/design/{ => sarif}/sarif-result.md (100%) rename docs/design/{ => sarif}/sarif-results.md (100%) rename docs/design/{ => sarif}/sarif.md (100%) create mode 100644 docs/design/self-test/self-test.md rename docs/design/{ => self-test}/validation.md (100%) rename docs/design/{ => utilities}/path-helpers.md (100%) create mode 100644 docs/design/utilities/utilities.md rename docs/reqstream/{ => cli}/context.yaml (100%) rename docs/reqstream/{command-line.yaml => cli/subsystem-cli.yaml} (100%) rename docs/reqstream/{ => sarif}/sarif-result.yaml (100%) rename docs/reqstream/{ => sarif}/sarif-results.yaml (100%) rename docs/reqstream/{report.yaml => sarif/subsystem-report.yaml} (100%) rename docs/reqstream/{sarif.yaml => sarif/subsystem-sarif.yaml} (100%) create mode 100644 docs/reqstream/sarifmark-system.yaml rename docs/reqstream/{validation.yaml => self-test/subsystem-self-test.yaml} (100%) rename docs/reqstream/{ => self-test}/validation-class.yaml (100%) rename docs/reqstream/{ => utilities}/path-helpers.yaml (100%) create mode 100644 docs/reqstream/utilities/subsystem-utilities.yaml rename src/DemaConsulting.SarifMark/{ => Cli}/Context.cs (100%) rename src/DemaConsulting.SarifMark/{ => Sarif}/SarifResult.cs (100%) rename src/DemaConsulting.SarifMark/{ => Sarif}/SarifResults.cs (100%) rename src/DemaConsulting.SarifMark/{ => SelfTest}/Validation.cs (100%) rename src/DemaConsulting.SarifMark/{ => Utilities}/PathHelpers.cs (100%) rename test/DemaConsulting.SarifMark.Tests/{ => Cli}/ContextTests.cs (100%) rename test/DemaConsulting.SarifMark.Tests/{ => Sarif}/SarifResultsTests.cs (100%) rename test/DemaConsulting.SarifMark.Tests/{ => SelfTest}/ValidationTests.cs (100%) rename test/DemaConsulting.SarifMark.Tests/{ => Utilities}/PathHelpersTests.cs (100%) diff --git a/.reviewmark.yaml b/.reviewmark.yaml index a4c2c46..22dad67 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -7,6 +7,7 @@ # Processed in order; prefix a pattern with '!' to exclude. needs-review: - "**/*.cs" # All C# source and test files + - "requirements.yaml" # Root requirements file - "docs/reqstream/**/*.yaml" # Requirements files - "docs/design/**/*.md" # Design documents - "!**/obj/**" # Exclude build output @@ -23,60 +24,71 @@ evidence-source: # Software unit reviews cover the internal design and implementation of each individual class. reviews: - # --------------------------------------------------------------------------- - # Subsystem Reviews - # --------------------------------------------------------------------------- - - - id: SarifMark-CommandLine-Subsystem-Review - title: Review of SarifMark Command-Line Interface Subsystem + # System review + - id: SarifMark-System + title: Review of SarifMark System paths: - - "docs/reqstream/command-line.yaml" - - "docs/reqstream/program.yaml" - - "docs/reqstream/context.yaml" + - "docs/reqstream/sarifmark-system.yaml" - "docs/design/introduction.md" - - "docs/design/command-line.md" + - "docs/reqstream/program.yaml" - "docs/design/program.md" - - "docs/design/context.md" - "src/**/Program.cs" - - "src/**/Context.cs" - "test/**/ProgramTests.cs" - - "test/**/ContextTests.cs" - "test/**/IntegrationTests.cs" - "test/**/Runner.cs" - "test/**/AssemblyInfo.cs" + # All requirements review + - id: SarifMark-AllRequirements + title: Review of All SarifMark Requirements + paths: + - "requirements.yaml" + - "docs/reqstream/**/*.yaml" + + # --------------------------------------------------------------------------- + # Subsystem Reviews + # --------------------------------------------------------------------------- + + - id: SarifMark-Cli-Subsystem-Review + title: Review of SarifMark Command-Line Interface Subsystem + paths: + - "docs/reqstream/cli/subsystem-cli.yaml" + - "docs/design/cli/cli.md" + - "docs/design/cli/context.md" + - "src/**/Cli/Context.cs" + - "test/**/Cli/ContextTests.cs" + - id: SarifMark-Sarif-Subsystem-Review title: Review of SarifMark SARIF Reading Subsystem paths: - - "docs/reqstream/sarif.yaml" - - "docs/reqstream/sarif-result.yaml" - - "docs/reqstream/sarif-results.yaml" - - "docs/design/sarif.md" - - "src/**/SarifResult.cs" - - "src/**/SarifResults.cs" - - "test/**/SarifResultsTests.cs" + - "docs/reqstream/sarif/subsystem-sarif.yaml" + - "docs/reqstream/sarif/subsystem-report.yaml" + - "docs/design/sarif/sarif.md" + - "docs/design/sarif/sarif-result.md" + - "docs/design/sarif/sarif-results.md" + - "src/**/Sarif/SarifResult.cs" + - "src/**/Sarif/SarifResults.cs" + - "test/**/Sarif/SarifResultsTests.cs" - "test/**/IntegrationTests.cs" - - id: SarifMark-Report-Subsystem-Review - title: Review of SarifMark Report Generation Subsystem + - id: SarifMark-SelfTest-Subsystem-Review + title: Review of SarifMark Self-Validation Subsystem paths: - - "docs/reqstream/report.yaml" - - "docs/reqstream/sarif-results.yaml" - - "docs/design/sarif.md" - - "docs/design/sarif-results.md" - - "src/**/SarifResults.cs" - - "test/**/SarifResultsTests.cs" + - "docs/reqstream/self-test/subsystem-self-test.yaml" + - "docs/design/self-test/self-test.md" + - "docs/design/self-test/validation.md" + - "src/**/SelfTest/Validation.cs" + - "test/**/SelfTest/ValidationTests.cs" - "test/**/IntegrationTests.cs" - - id: SarifMark-Validation-Subsystem-Review - title: Review of SarifMark Self-Validation Subsystem + - id: SarifMark-Utilities-Subsystem-Review + title: Review of SarifMark Utilities Subsystem paths: - - "docs/reqstream/validation.yaml" - - "docs/reqstream/validation-class.yaml" - - "docs/design/validation.md" - - "src/**/Validation.cs" - - "test/**/ValidationTests.cs" - - "test/**/IntegrationTests.cs" + - "docs/reqstream/utilities/subsystem-utilities.yaml" + - "docs/design/utilities/utilities.md" + - "docs/design/utilities/path-helpers.md" + - "src/**/Utilities/PathHelpers.cs" + - "test/**/Utilities/PathHelpersTests.cs" - id: SarifMark-Platform-Subsystem-Review title: Review of SarifMark Platform and OTS Software @@ -95,46 +107,43 @@ reviews: - "docs/design/program.md" - "src/**/Program.cs" - "test/**/ProgramTests.cs" - - "test/**/IntegrationTests.cs" - - "test/**/Runner.cs" - - "test/**/AssemblyInfo.cs" - id: SarifMark-Context-SoftwareUnit-Review title: Review of SarifMark Context Software Unit paths: - - "docs/reqstream/context.yaml" - - "docs/design/context.md" - - "src/**/Context.cs" - - "test/**/ContextTests.cs" + - "docs/reqstream/cli/context.yaml" + - "docs/design/cli/context.md" + - "src/**/Cli/Context.cs" + - "test/**/Cli/ContextTests.cs" - id: SarifMark-SarifResult-SoftwareUnit-Review title: Review of SarifMark SarifResult Software Unit paths: - - "docs/reqstream/sarif-result.yaml" - - "docs/design/sarif-result.md" - - "src/**/SarifResult.cs" - - "test/**/SarifResultsTests.cs" + - "docs/reqstream/sarif/sarif-result.yaml" + - "docs/design/sarif/sarif-result.md" + - "src/**/Sarif/SarifResult.cs" + - "test/**/Sarif/SarifResultsTests.cs" - id: SarifMark-SarifResults-SoftwareUnit-Review title: Review of SarifMark SarifResults Software Unit paths: - - "docs/reqstream/sarif-results.yaml" - - "docs/design/sarif-results.md" - - "src/**/SarifResults.cs" - - "test/**/SarifResultsTests.cs" + - "docs/reqstream/sarif/sarif-results.yaml" + - "docs/design/sarif/sarif-results.md" + - "src/**/Sarif/SarifResults.cs" + - "test/**/Sarif/SarifResultsTests.cs" - id: SarifMark-Validation-SoftwareUnit-Review title: Review of SarifMark Validation Software Unit paths: - - "docs/reqstream/validation-class.yaml" - - "docs/design/validation.md" - - "src/**/Validation.cs" - - "test/**/ValidationTests.cs" + - "docs/reqstream/self-test/validation-class.yaml" + - "docs/design/self-test/validation.md" + - "src/**/SelfTest/Validation.cs" + - "test/**/SelfTest/ValidationTests.cs" - id: SarifMark-PathHelpers-SoftwareUnit-Review title: Review of SarifMark PathHelpers Software Unit paths: - - "docs/reqstream/path-helpers.yaml" - - "docs/design/path-helpers.md" - - "src/**/PathHelpers.cs" - - "test/**/PathHelpersTests.cs" + - "docs/reqstream/utilities/path-helpers.yaml" + - "docs/design/utilities/path-helpers.md" + - "src/**/Utilities/PathHelpers.cs" + - "test/**/Utilities/PathHelpersTests.cs" diff --git a/AGENTS.md b/AGENTS.md index 1814666..828dc1e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -92,6 +92,8 @@ compliance gates on every CI/CD run instead of as a last-mile activity. ## Project Structure Template - `docs/` - Documentation and compliance artifacts + - `design/` - Detailed design documents + - `introduction.md` - System/Subsystem/Unit breakdown for this repository - `reqstream/` - Subsystem requirements YAML files (included by root requirements.yaml) - Auto-generated reports (requirements, justifications, trace matrix) - `src/` - Source code files diff --git a/docs/design/cli/cli.md b/docs/design/cli/cli.md new file mode 100644 index 0000000..8bfa19c --- /dev/null +++ b/docs/design/cli/cli.md @@ -0,0 +1,41 @@ +# Cli Subsystem + +The `Cli` subsystem provides the command-line interface for SarifMark. +It is responsible for accepting user input from the command line and routing output to +the console and an optional log file. + +## Overview + +The `Cli` subsystem acts as the primary boundary between the user's shell invocation and +the tool's internal logic. It owns argument parsing, output formatting, and error tracking. +All other subsystems receive a `Context` object from the `Cli` subsystem to read parsed +flags and write output. + +## Units + +The `Cli` subsystem contains the following software unit: + +| Unit | File | Responsibility | +|-----------|------------------|---------------------------------------------------| +| `Context` | `Cli/Context.cs` | Argument parsing, output channels, and exit code. | + +## Interfaces + +The `Cli` subsystem exposes the following interface to the rest of the tool: + +| Interface | Direction | Description | +|----------------------|-----------|---------------------------------------------------------------| +| `Context.Create` | Outbound | Factory method constructing a `Context` from `string[] args`. | +| `Context.WriteLine` | Outbound | Writes a message to console and optional log file. | +| `Context.WriteError` | Outbound | Writes an error to stderr and sets the error exit code. | +| `Context.ExitCode` | Outbound | Returns 0 for success or 1 when errors have been reported. | + +## Interactions + +The `Cli` subsystem has no dependencies on other tool subsystems. It uses only .NET base +class library types. The `Program` unit at system level creates the `Context` and passes it +to all subsystems that need to produce output. + +## Class Details + +- **Context class** — argument parsing and output routing diff --git a/docs/design/context.md b/docs/design/cli/context.md similarity index 100% rename from docs/design/context.md rename to docs/design/cli/context.md diff --git a/docs/design/command-line.md b/docs/design/command-line.md deleted file mode 100644 index d8ac592..0000000 --- a/docs/design/command-line.md +++ /dev/null @@ -1,52 +0,0 @@ -# Command Line - -## Overview - -The command-line layer is responsible for parsing command-line arguments, routing program -flow to the appropriate subsystem, and managing all output (console, error, and log file). -It consists of two classes: `Program` (the entry point) and -`Context` (the argument and output container). This layer satisfies -requirements `SarifMark-Cli-Interface`, `SarifMark-Cli-Version`, `SarifMark-Cli-Help`, -`SarifMark-Cli-Silent`, `SarifMark-Cli-Log`, `SarifMark-Cli-Enforce`, and -`SarifMark-Cli-InvalidArgs`. - -## Architecture - -The command-line layer uses a two-class design: - -- **`Program`** is the static entry point. It owns `Main`, constructs a `Context`, and - dispatches execution to the appropriate subsystem via priority-ordered logic. See the - Program Class document for class-level details. - -- **`Context`** is a sealed, disposable container for all parsed command-line state and - output routing. It accumulates argument values during parsing and provides - `WriteLine`/`WriteError` methods used throughout the tool. See the Context Class document - for class-level details. - -## Dispatch Model - -`Program.Run` evaluates conditions in a fixed priority order and returns after the first -matching condition: - -| Priority | Condition | Action | -|----------|--------------------|-------------------------------------| -| 1 | `context.Version` | Print version string and return | -| — | *(always)* | Print banner | -| 2 | `context.Help` | Print usage and return | -| 3 | `context.Validate` | Run self-validation and return | -| 4 | *(default)* | Run SARIF analysis processing | - -This satisfies requirements `SarifMark-Cli-Version`, `SarifMark-Cli-Help`, and -`SarifMark-Validate-Mode`. - -## SARIF Analysis Orchestration - -When no informational flag is set, `Program.ProcessSarifAnalysis` validates that `--sarif` -is provided, reads and processes the SARIF file, optionally enforces a quality gate, and -optionally writes a markdown report. This satisfies requirements `SarifMark-Sarif-Required`, -`SarifMark-Enforce-Mode`, and `SarifMark-Report-Markdown`. - -## Class Details - -- **Program class** — entry point, dispatch, and SARIF analysis orchestration -- **Context class** — argument parsing and output routing diff --git a/docs/design/definition.yaml b/docs/design/definition.yaml index e065ba2..a2eed9f 100644 --- a/docs/design/definition.yaml +++ b/docs/design/definition.yaml @@ -1,18 +1,24 @@ --- resource-path: - docs/design + - docs/design/cli + - docs/design/sarif + - docs/design/self-test + - docs/design/utilities - docs/template input-files: - docs/design/title.txt - docs/design/introduction.md - - docs/design/command-line.md - - docs/design/sarif.md - - docs/design/validation.md - docs/design/program.md - - docs/design/context.md - - docs/design/sarif-result.md - - docs/design/sarif-results.md - - docs/design/path-helpers.md + - docs/design/cli/cli.md + - docs/design/cli/context.md + - docs/design/sarif/sarif.md + - docs/design/sarif/sarif-result.md + - docs/design/sarif/sarif-results.md + - docs/design/self-test/self-test.md + - docs/design/self-test/validation.md + - docs/design/utilities/utilities.md + - docs/design/utilities/path-helpers.md template: template.html table-of-contents: true number-sections: true diff --git a/docs/design/introduction.md b/docs/design/introduction.md index b8ced6f..a35218c 100644 --- a/docs/design/introduction.md +++ b/docs/design/introduction.md @@ -42,6 +42,48 @@ This document is intended for: Readers are assumed to be familiar with C# and .NET development and general concepts of command-line tool design. +## Software Structure + +The following tree shows how the SarifMark software items are organized across the +system, subsystem, and unit levels: + +```text +SarifMark (System) +├── Program (Unit) +├── Cli (Subsystem) +│ └── Context (Unit) +├── Sarif (Subsystem) +│ ├── SarifResult (Unit) +│ └── SarifResults (Unit) +├── SelfTest (Subsystem) +│ └── Validation (Unit) +└── Utilities (Subsystem) + └── PathHelpers (Unit) +``` + +Each unit is described in detail in its own chapter within this document. + +## Folder Layout + +The source code folder structure mirrors the top-level subsystem breakdown above, giving +reviewers an explicit navigation aid from design to code: + +```text +src/DemaConsulting.SarifMark/ +├── Program.cs — entry point and execution orchestrator +├── Cli/ +│ └── Context.cs — command-line argument parser and I/O owner +├── Sarif/ +│ ├── SarifResult.cs — immutable record for a single analysis finding +│ └── SarifResults.cs — SARIF file reading and markdown report generation +├── SelfTest/ +│ └── Validation.cs — self-validation test runner +└── Utilities/ + └── PathHelpers.cs — safe path combination utilities +``` + +The test project mirrors the same layout under `test/DemaConsulting.SarifMark.Tests/`. + ## Relationship to Requirements and Code Each component described here corresponds to one or more requirements defined in the diff --git a/docs/design/sarif-result.md b/docs/design/sarif/sarif-result.md similarity index 100% rename from docs/design/sarif-result.md rename to docs/design/sarif/sarif-result.md diff --git a/docs/design/sarif-results.md b/docs/design/sarif/sarif-results.md similarity index 100% rename from docs/design/sarif-results.md rename to docs/design/sarif/sarif-results.md diff --git a/docs/design/sarif.md b/docs/design/sarif/sarif.md similarity index 100% rename from docs/design/sarif.md rename to docs/design/sarif/sarif.md diff --git a/docs/design/self-test/self-test.md b/docs/design/self-test/self-test.md new file mode 100644 index 0000000..79e044a --- /dev/null +++ b/docs/design/self-test/self-test.md @@ -0,0 +1,39 @@ +# SelfTest Subsystem + +The `SelfTest` subsystem provides the self-validation framework for SarifMark. +It runs a built-in suite of tests to demonstrate the tool is functioning correctly in the +deployment environment. + +## Overview + +The `SelfTest` subsystem is invoked when the user passes `--validate` on the command line. +It exercises the tool's own capabilities and reports a pass/fail summary. It can also write +test results to a file in TRX or JUnit XML format for integration with CI/CD pipelines. + +## Units + +The `SelfTest` subsystem contains the following software unit: + +| Unit | File | Responsibility | +|--------------|--------------------------|----------------------------------------------------| +| `Validation` | `SelfTest/Validation.cs` | Orchestrating and executing self-validation tests. | + +## Interfaces + +The `SelfTest` subsystem exposes the following interface to the rest of the tool: + +| Interface | Direction | Description | +|------------------|-----------|-----------------------------------------------------------------------| +| `Validation.Run` | Outbound | Runs all self-validation tests, prints a summary, and writes results. | + +## Interactions + +| Dependency | Direction | Purpose | +|---------------|-----------|--------------------------------------------------------------| +| `Context` | Uses | Output channel for header lines, test summaries, and errors. | +| `Program` | Uses | `Program.Run` is called internally to exercise the tool. | +| `PathHelpers` | Uses | `SafePathCombine` for constructing log file paths in tests. | + +## Class Details + +- **Validation class** — self-validation test runner diff --git a/docs/design/validation.md b/docs/design/self-test/validation.md similarity index 100% rename from docs/design/validation.md rename to docs/design/self-test/validation.md diff --git a/docs/design/path-helpers.md b/docs/design/utilities/path-helpers.md similarity index 100% rename from docs/design/path-helpers.md rename to docs/design/utilities/path-helpers.md diff --git a/docs/design/utilities/utilities.md b/docs/design/utilities/utilities.md new file mode 100644 index 0000000..97fe907 --- /dev/null +++ b/docs/design/utilities/utilities.md @@ -0,0 +1,36 @@ +# Utilities Subsystem + +The `Utilities` subsystem provides shared utility functions for SarifMark. +It supplies reusable, independently testable helpers that are consumed by other subsystems. + +## Overview + +The `Utilities` subsystem contains general-purpose helpers that do not belong to any +specific feature subsystem. Its primary responsibility is safe file-path manipulation, +protecting callers from path-traversal vulnerabilities when constructing paths from +external inputs. + +## Units + +The `Utilities` subsystem contains the following software unit: + +| Unit | File | Responsibility | +|---------------|----------------------------|---------------------------------------------| +| `PathHelpers` | `Utilities/PathHelpers.cs` | Safe path combination and traversal checks. | + +## Interfaces + +The `Utilities` subsystem exposes the following interface to the rest of the tool: + +| Interface | Direction | Description | +|-------------------------------|-----------|------------------------------------------------------------| +| `PathHelpers.SafePathCombine` | Outbound | Combines two path segments, rejecting traversal sequences. | + +## Interactions + +`PathHelpers` has no dependencies on other tool units or subsystems. It uses only .NET base +class library types (`Path`, `ArgumentNullException`). + +## Class Details + +- **PathHelpers class** — safe path combination utilities diff --git a/docs/reqstream/context.yaml b/docs/reqstream/cli/context.yaml similarity index 100% rename from docs/reqstream/context.yaml rename to docs/reqstream/cli/context.yaml diff --git a/docs/reqstream/command-line.yaml b/docs/reqstream/cli/subsystem-cli.yaml similarity index 100% rename from docs/reqstream/command-line.yaml rename to docs/reqstream/cli/subsystem-cli.yaml diff --git a/docs/reqstream/sarif-result.yaml b/docs/reqstream/sarif/sarif-result.yaml similarity index 100% rename from docs/reqstream/sarif-result.yaml rename to docs/reqstream/sarif/sarif-result.yaml diff --git a/docs/reqstream/sarif-results.yaml b/docs/reqstream/sarif/sarif-results.yaml similarity index 100% rename from docs/reqstream/sarif-results.yaml rename to docs/reqstream/sarif/sarif-results.yaml diff --git a/docs/reqstream/report.yaml b/docs/reqstream/sarif/subsystem-report.yaml similarity index 100% rename from docs/reqstream/report.yaml rename to docs/reqstream/sarif/subsystem-report.yaml diff --git a/docs/reqstream/sarif.yaml b/docs/reqstream/sarif/subsystem-sarif.yaml similarity index 100% rename from docs/reqstream/sarif.yaml rename to docs/reqstream/sarif/subsystem-sarif.yaml diff --git a/docs/reqstream/sarifmark-system.yaml b/docs/reqstream/sarifmark-system.yaml new file mode 100644 index 0000000..a2b5256 --- /dev/null +++ b/docs/reqstream/sarifmark-system.yaml @@ -0,0 +1,79 @@ +--- +# SarifMark System-Level Requirements +# +# PURPOSE: +# - Define system-level requirements describing what end-users need the tool to provide +# - These requirements capture the externally visible behavior of the complete system +# - System requirements are validated through integration tests that exercise the +# published dotnet DLL end-to-end + +sections: + - title: System-Level Requirements + requirements: + - id: SarifMark-System-Version + title: The tool shall display version information when the version flag is provided. + justification: >- + Users need to quickly identify the version of the tool they are using for + troubleshooting and compatibility verification. + tests: + - IntegrationTest_VersionFlag_OutputsVersion + + - id: SarifMark-System-Help + title: The tool shall display help information when the help flag is provided. + justification: >- + Help information improves discoverability and usability by providing users with guidance + on available options and parameters. + tests: + - IntegrationTest_HelpFlag_OutputsUsageInformation + + - id: SarifMark-System-Validate + title: The tool shall support self-validation mode. + justification: >- + Self-validation mode enables verification that the tool operates correctly in + the deployment environment. + tests: + - IntegrationTest_ValidateFlag_RunsSelfValidation + + - id: SarifMark-System-SarifAnalysis + title: The tool shall read and analyze SARIF files. + justification: >- + Reading and analyzing SARIF files is the core purpose of the tool, enabling + integration with static analysis workflows. + tests: + - IntegrationTest_SarifFile_ProcessesSarifFile + + - id: SarifMark-System-Report + title: The tool shall generate markdown reports from SARIF files. + justification: >- + Markdown report generation makes SARIF analysis results accessible to + stakeholders in a readable format. + tests: + - IntegrationTest_ReportFile_GeneratesMarkdownReport + + - id: SarifMark-System-Enforce + title: The tool shall return non-zero exit code when enforcement mode detects issues. + justification: >- + Non-zero exit codes enable CI/CD pipeline integration for quality gates. + tests: + - IntegrationTest_EnforceFlagWithIssues_ReturnsError + + - id: SarifMark-System-Silent + title: The tool shall support silent mode to suppress console output. + justification: >- + Silent mode enables cleaner integration into automated workflows. + tests: + - IntegrationTest_SilentFlag_SuppressesOutput + + - id: SarifMark-System-LogFile + title: The tool shall support writing output to a log file. + justification: >- + Log file support enables persistent record-keeping and audit trails. + tests: + - IntegrationTest_LogFile_WritesOutputToFile + + - id: SarifMark-System-InvalidArgs + title: The tool shall reject unknown command-line arguments with an error. + justification: >- + Rejecting unknown arguments prevents silent failures from typos. + tests: + - IntegrationTest_UnknownArgument_ShowsError diff --git a/docs/reqstream/validation.yaml b/docs/reqstream/self-test/subsystem-self-test.yaml similarity index 100% rename from docs/reqstream/validation.yaml rename to docs/reqstream/self-test/subsystem-self-test.yaml diff --git a/docs/reqstream/validation-class.yaml b/docs/reqstream/self-test/validation-class.yaml similarity index 100% rename from docs/reqstream/validation-class.yaml rename to docs/reqstream/self-test/validation-class.yaml diff --git a/docs/reqstream/path-helpers.yaml b/docs/reqstream/utilities/path-helpers.yaml similarity index 100% rename from docs/reqstream/path-helpers.yaml rename to docs/reqstream/utilities/path-helpers.yaml diff --git a/docs/reqstream/utilities/subsystem-utilities.yaml b/docs/reqstream/utilities/subsystem-utilities.yaml new file mode 100644 index 0000000..b62c66a --- /dev/null +++ b/docs/reqstream/utilities/subsystem-utilities.yaml @@ -0,0 +1,18 @@ +--- +sections: + - title: SarifMark Requirements + sections: + - title: Utilities Subsystem + requirements: + - id: SarifMark-Utilities-SafePathHandling + title: The Utilities subsystem shall provide safe path-handling functions for use by other subsystems. + justification: >- + Centralizing path-safety logic in a dedicated subsystem prevents path-traversal vulnerabilities + from being independently reimplemented across the codebase and ensures consistent, auditable + protection wherever external inputs are combined with base paths. + tags: [internal] + children: + - SarifMark-PathHelpers-SafeCombine + - SarifMark-PathHelpers-TraversalCheck + tests: + - PathHelpers_SafePathCombine_ValidPaths_CombinesSuccessfully diff --git a/requirements.yaml b/requirements.yaml index b5344d1..864e9e5 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -13,15 +13,17 @@ # --- includes: - - docs/reqstream/command-line.yaml - - docs/reqstream/sarif.yaml - - docs/reqstream/report.yaml - - docs/reqstream/validation.yaml + - docs/reqstream/sarifmark-system.yaml + - docs/reqstream/cli/subsystem-cli.yaml + - docs/reqstream/cli/context.yaml + - docs/reqstream/sarif/subsystem-sarif.yaml + - docs/reqstream/sarif/subsystem-report.yaml + - docs/reqstream/sarif/sarif-result.yaml + - docs/reqstream/sarif/sarif-results.yaml + - docs/reqstream/self-test/subsystem-self-test.yaml + - docs/reqstream/self-test/validation-class.yaml + - docs/reqstream/utilities/subsystem-utilities.yaml + - docs/reqstream/utilities/path-helpers.yaml - docs/reqstream/platform.yaml - docs/reqstream/ots-software.yaml - docs/reqstream/program.yaml - - docs/reqstream/context.yaml - - docs/reqstream/sarif-result.yaml - - docs/reqstream/sarif-results.yaml - - docs/reqstream/validation-class.yaml - - docs/reqstream/path-helpers.yaml diff --git a/src/DemaConsulting.SarifMark/Context.cs b/src/DemaConsulting.SarifMark/Cli/Context.cs similarity index 100% rename from src/DemaConsulting.SarifMark/Context.cs rename to src/DemaConsulting.SarifMark/Cli/Context.cs diff --git a/src/DemaConsulting.SarifMark/SarifResult.cs b/src/DemaConsulting.SarifMark/Sarif/SarifResult.cs similarity index 100% rename from src/DemaConsulting.SarifMark/SarifResult.cs rename to src/DemaConsulting.SarifMark/Sarif/SarifResult.cs diff --git a/src/DemaConsulting.SarifMark/SarifResults.cs b/src/DemaConsulting.SarifMark/Sarif/SarifResults.cs similarity index 100% rename from src/DemaConsulting.SarifMark/SarifResults.cs rename to src/DemaConsulting.SarifMark/Sarif/SarifResults.cs diff --git a/src/DemaConsulting.SarifMark/Validation.cs b/src/DemaConsulting.SarifMark/SelfTest/Validation.cs similarity index 100% rename from src/DemaConsulting.SarifMark/Validation.cs rename to src/DemaConsulting.SarifMark/SelfTest/Validation.cs diff --git a/src/DemaConsulting.SarifMark/PathHelpers.cs b/src/DemaConsulting.SarifMark/Utilities/PathHelpers.cs similarity index 100% rename from src/DemaConsulting.SarifMark/PathHelpers.cs rename to src/DemaConsulting.SarifMark/Utilities/PathHelpers.cs diff --git a/test/DemaConsulting.SarifMark.Tests/ContextTests.cs b/test/DemaConsulting.SarifMark.Tests/Cli/ContextTests.cs similarity index 100% rename from test/DemaConsulting.SarifMark.Tests/ContextTests.cs rename to test/DemaConsulting.SarifMark.Tests/Cli/ContextTests.cs diff --git a/test/DemaConsulting.SarifMark.Tests/SarifResultsTests.cs b/test/DemaConsulting.SarifMark.Tests/Sarif/SarifResultsTests.cs similarity index 100% rename from test/DemaConsulting.SarifMark.Tests/SarifResultsTests.cs rename to test/DemaConsulting.SarifMark.Tests/Sarif/SarifResultsTests.cs diff --git a/test/DemaConsulting.SarifMark.Tests/ValidationTests.cs b/test/DemaConsulting.SarifMark.Tests/SelfTest/ValidationTests.cs similarity index 100% rename from test/DemaConsulting.SarifMark.Tests/ValidationTests.cs rename to test/DemaConsulting.SarifMark.Tests/SelfTest/ValidationTests.cs diff --git a/test/DemaConsulting.SarifMark.Tests/PathHelpersTests.cs b/test/DemaConsulting.SarifMark.Tests/Utilities/PathHelpersTests.cs similarity index 100% rename from test/DemaConsulting.SarifMark.Tests/PathHelpersTests.cs rename to test/DemaConsulting.SarifMark.Tests/Utilities/PathHelpersTests.cs From 9c2db46f71e3c4351fa4c64fb9268a752007aeda Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 18:55:26 +0000 Subject: [PATCH 3/7] Fix review conventions: add system.md, rename reqstream files, fix review-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> --- .reviewmark.yaml | 53 ++++++------ docs/design/definition.yaml | 1 + docs/design/system.md | 81 +++++++++++++++++++ .../cli/{context.yaml => unit-context.yaml} | 0 ...atform.yaml => platform-requirements.yaml} | 0 ...rif-result.yaml => unit-sarif-result.yaml} | 0 ...f-results.yaml => unit-sarif-results.yaml} | 0 ...dation-class.yaml => unit-validation.yaml} | 0 .../{program.yaml => unit-program.yaml} | 0 ...th-helpers.yaml => unit-path-helpers.yaml} | 0 requirements.yaml | 14 ++-- 11 files changed, 117 insertions(+), 32 deletions(-) create mode 100644 docs/design/system.md rename docs/reqstream/cli/{context.yaml => unit-context.yaml} (100%) rename docs/reqstream/{platform.yaml => platform-requirements.yaml} (100%) rename docs/reqstream/sarif/{sarif-result.yaml => unit-sarif-result.yaml} (100%) rename docs/reqstream/sarif/{sarif-results.yaml => unit-sarif-results.yaml} (100%) rename docs/reqstream/self-test/{validation-class.yaml => unit-validation.yaml} (100%) rename docs/reqstream/{program.yaml => unit-program.yaml} (100%) rename docs/reqstream/utilities/{path-helpers.yaml => unit-path-helpers.yaml} (100%) diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 22dad67..196c965 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -24,13 +24,19 @@ evidence-source: # Software unit reviews cover the internal design and implementation of each individual class. reviews: - # System review + # --------------------------------------------------------------------------- + # System Review + # --------------------------------------------------------------------------- + - id: SarifMark-System title: Review of SarifMark System paths: - "docs/reqstream/sarifmark-system.yaml" + - "docs/reqstream/platform-requirements.yaml" + - "docs/reqstream/ots-software.yaml" - "docs/design/introduction.md" - - "docs/reqstream/program.yaml" + - "docs/design/system.md" + - "docs/reqstream/unit-program.yaml" - "docs/design/program.md" - "src/**/Program.cs" - "test/**/ProgramTests.cs" @@ -38,7 +44,10 @@ reviews: - "test/**/Runner.cs" - "test/**/AssemblyInfo.cs" - # All requirements review + # --------------------------------------------------------------------------- + # All Requirements Review + # --------------------------------------------------------------------------- + - id: SarifMark-AllRequirements title: Review of All SarifMark Requirements paths: @@ -49,7 +58,7 @@ reviews: # Subsystem Reviews # --------------------------------------------------------------------------- - - id: SarifMark-Cli-Subsystem-Review + - id: SarifMark-Cli title: Review of SarifMark Command-Line Interface Subsystem paths: - "docs/reqstream/cli/subsystem-cli.yaml" @@ -58,7 +67,7 @@ reviews: - "src/**/Cli/Context.cs" - "test/**/Cli/ContextTests.cs" - - id: SarifMark-Sarif-Subsystem-Review + - id: SarifMark-Sarif title: Review of SarifMark SARIF Reading Subsystem paths: - "docs/reqstream/sarif/subsystem-sarif.yaml" @@ -71,7 +80,7 @@ reviews: - "test/**/Sarif/SarifResultsTests.cs" - "test/**/IntegrationTests.cs" - - id: SarifMark-SelfTest-Subsystem-Review + - id: SarifMark-SelfTest title: Review of SarifMark Self-Validation Subsystem paths: - "docs/reqstream/self-test/subsystem-self-test.yaml" @@ -81,7 +90,7 @@ reviews: - "test/**/SelfTest/ValidationTests.cs" - "test/**/IntegrationTests.cs" - - id: SarifMark-Utilities-Subsystem-Review + - id: SarifMark-Utilities title: Review of SarifMark Utilities Subsystem paths: - "docs/reqstream/utilities/subsystem-utilities.yaml" @@ -90,60 +99,54 @@ reviews: - "src/**/Utilities/PathHelpers.cs" - "test/**/Utilities/PathHelpersTests.cs" - - id: SarifMark-Platform-Subsystem-Review - title: Review of SarifMark Platform and OTS Software - paths: - - "docs/reqstream/platform.yaml" - - "docs/reqstream/ots-software.yaml" - # --------------------------------------------------------------------------- # Software Unit Reviews # --------------------------------------------------------------------------- - - id: SarifMark-Program-SoftwareUnit-Review + - id: SarifMark-Program title: Review of SarifMark Program Software Unit paths: - - "docs/reqstream/program.yaml" + - "docs/reqstream/unit-program.yaml" - "docs/design/program.md" - "src/**/Program.cs" - "test/**/ProgramTests.cs" - - id: SarifMark-Context-SoftwareUnit-Review + - id: SarifMark-Context title: Review of SarifMark Context Software Unit paths: - - "docs/reqstream/cli/context.yaml" + - "docs/reqstream/cli/unit-context.yaml" - "docs/design/cli/context.md" - "src/**/Cli/Context.cs" - "test/**/Cli/ContextTests.cs" - - id: SarifMark-SarifResult-SoftwareUnit-Review + - id: SarifMark-SarifResult title: Review of SarifMark SarifResult Software Unit paths: - - "docs/reqstream/sarif/sarif-result.yaml" + - "docs/reqstream/sarif/unit-sarif-result.yaml" - "docs/design/sarif/sarif-result.md" - "src/**/Sarif/SarifResult.cs" - "test/**/Sarif/SarifResultsTests.cs" - - id: SarifMark-SarifResults-SoftwareUnit-Review + - id: SarifMark-SarifResults title: Review of SarifMark SarifResults Software Unit paths: - - "docs/reqstream/sarif/sarif-results.yaml" + - "docs/reqstream/sarif/unit-sarif-results.yaml" - "docs/design/sarif/sarif-results.md" - "src/**/Sarif/SarifResults.cs" - "test/**/Sarif/SarifResultsTests.cs" - - id: SarifMark-Validation-SoftwareUnit-Review + - id: SarifMark-Validation title: Review of SarifMark Validation Software Unit paths: - - "docs/reqstream/self-test/validation-class.yaml" + - "docs/reqstream/self-test/unit-validation.yaml" - "docs/design/self-test/validation.md" - "src/**/SelfTest/Validation.cs" - "test/**/SelfTest/ValidationTests.cs" - - id: SarifMark-PathHelpers-SoftwareUnit-Review + - id: SarifMark-PathHelpers title: Review of SarifMark PathHelpers Software Unit paths: - - "docs/reqstream/utilities/path-helpers.yaml" + - "docs/reqstream/utilities/unit-path-helpers.yaml" - "docs/design/utilities/path-helpers.md" - "src/**/Utilities/PathHelpers.cs" - "test/**/Utilities/PathHelpersTests.cs" diff --git a/docs/design/definition.yaml b/docs/design/definition.yaml index a2eed9f..54a2856 100644 --- a/docs/design/definition.yaml +++ b/docs/design/definition.yaml @@ -9,6 +9,7 @@ resource-path: input-files: - docs/design/title.txt - docs/design/introduction.md + - docs/design/system.md - docs/design/program.md - docs/design/cli/cli.md - docs/design/cli/context.md diff --git a/docs/design/system.md b/docs/design/system.md new file mode 100644 index 0000000..048823b --- /dev/null +++ b/docs/design/system.md @@ -0,0 +1,81 @@ +# SarifMark System Design + +## Overview + +SarifMark is a .NET command-line tool that reads SARIF (Static Analysis Results +Interchange Format) 2.1.0 files and generates human-readable markdown reports. +It is designed for integration into CI/CD pipelines to surface static analysis +findings in pull requests, dashboards, and compliance documentation. + +## Subsystems + +The system is organized into four subsystems plus a system-level entry point: + +| Item | Type | Responsibility | +|---------------|------------|--------------------------------------------------------------| +| `Program` | Unit | Entry point, argument handling, and subsystem orchestration | +| `Cli` | Subsystem | Command-line argument parsing and console output routing | +| `Sarif` | Subsystem | SARIF file reading and markdown report generation | +| `SelfTest` | Subsystem | Built-in self-validation for tool qualification | +| `Utilities` | Subsystem | Shared utility helpers (safe path combination) | + +See the [Software Structure section of the introduction][introduction] for the +full system/subsystem/unit tree. + +## Entry Point and Execution Flow + +The system entry point is `Program.Main`. On every invocation it: + +1. Constructs a `Context` (owned by the `Cli` subsystem) from `string[] args`. +1. Delegates to `Program.Run`, which selects the execution mode based on the + parsed flags and calls the appropriate subsystem. +1. Returns `Context.ExitCode` to the shell (0 for success, 1 on error). + +`ArgumentException` and `InvalidOperationException` are caught at the +`Main` level and translated to exit code 1, so all error paths produce a +non-zero exit code without an unhandled-exception stack trace. + +`Program.Run` evaluates conditions in priority order: + +| Mode | Condition | Subsystem Invoked | +|------------|------------------------|--------------------------------------------| +| Version | `--version` flag | None (prints version string) | +| Help | `--help` flag | None (prints usage) | +| Validate | `--validate` flag | `SelfTest.Validation.Run` | +| Analysis | *(default)* | `Sarif.SarifResults.Read` + `ToMarkdown` | + +## Subsystem Interactions + +```text +┌─────────────────────────────────────────────────────────┐ +│ Program (system entry point) │ +│ ┌──────────┐ creates ┌────────────────────────┐ │ +│ │ │──────────>│ Cli.Context │ │ +│ │ Main / │ │ (args, output, exit) │ │ +│ │ Run │ └────────────────────────┘ │ +│ │ │ calls ┌──────────────────────────┐ │ +│ │ │──────────>│ SelfTest.Validation.Run │ │ +│ │ │ └──────────────────────────┘ │ +│ │ │ calls ┌──────────────────────────┐ │ +│ │ │──────────>│ Sarif.SarifResults.Read │ │ +│ │ │ │ Sarif.SarifResults.ToMarkdown│ +│ └──────────┘ └──────────────────────────┘ │ +└─────────────────────────────────────────────────────────┘ + │ uses + ▼ + ┌──────────────────┐ + │ Utilities. │ + │ PathHelpers │ + └──────────────────┘ +``` + +All subsystems receive a `Cli.Context` reference for output. The `Utilities` +subsystem is a stateless helper used by `SelfTest` for path construction. + +## System Requirements + +System-level requirements are captured in `docs/reqstream/sarifmark-system.yaml` +and are validated through integration tests that exercise the published dotnet +DLL end-to-end across the supported platforms. + +[introduction]: introduction.md diff --git a/docs/reqstream/cli/context.yaml b/docs/reqstream/cli/unit-context.yaml similarity index 100% rename from docs/reqstream/cli/context.yaml rename to docs/reqstream/cli/unit-context.yaml diff --git a/docs/reqstream/platform.yaml b/docs/reqstream/platform-requirements.yaml similarity index 100% rename from docs/reqstream/platform.yaml rename to docs/reqstream/platform-requirements.yaml diff --git a/docs/reqstream/sarif/sarif-result.yaml b/docs/reqstream/sarif/unit-sarif-result.yaml similarity index 100% rename from docs/reqstream/sarif/sarif-result.yaml rename to docs/reqstream/sarif/unit-sarif-result.yaml diff --git a/docs/reqstream/sarif/sarif-results.yaml b/docs/reqstream/sarif/unit-sarif-results.yaml similarity index 100% rename from docs/reqstream/sarif/sarif-results.yaml rename to docs/reqstream/sarif/unit-sarif-results.yaml diff --git a/docs/reqstream/self-test/validation-class.yaml b/docs/reqstream/self-test/unit-validation.yaml similarity index 100% rename from docs/reqstream/self-test/validation-class.yaml rename to docs/reqstream/self-test/unit-validation.yaml diff --git a/docs/reqstream/program.yaml b/docs/reqstream/unit-program.yaml similarity index 100% rename from docs/reqstream/program.yaml rename to docs/reqstream/unit-program.yaml diff --git a/docs/reqstream/utilities/path-helpers.yaml b/docs/reqstream/utilities/unit-path-helpers.yaml similarity index 100% rename from docs/reqstream/utilities/path-helpers.yaml rename to docs/reqstream/utilities/unit-path-helpers.yaml diff --git a/requirements.yaml b/requirements.yaml index 864e9e5..2e25bbb 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -15,15 +15,15 @@ includes: - docs/reqstream/sarifmark-system.yaml - docs/reqstream/cli/subsystem-cli.yaml - - docs/reqstream/cli/context.yaml + - docs/reqstream/cli/unit-context.yaml - docs/reqstream/sarif/subsystem-sarif.yaml - docs/reqstream/sarif/subsystem-report.yaml - - docs/reqstream/sarif/sarif-result.yaml - - docs/reqstream/sarif/sarif-results.yaml + - docs/reqstream/sarif/unit-sarif-result.yaml + - docs/reqstream/sarif/unit-sarif-results.yaml - docs/reqstream/self-test/subsystem-self-test.yaml - - docs/reqstream/self-test/validation-class.yaml + - docs/reqstream/self-test/unit-validation.yaml - docs/reqstream/utilities/subsystem-utilities.yaml - - docs/reqstream/utilities/path-helpers.yaml - - docs/reqstream/platform.yaml + - docs/reqstream/utilities/unit-path-helpers.yaml + - docs/reqstream/platform-requirements.yaml - docs/reqstream/ots-software.yaml - - docs/reqstream/program.yaml + - docs/reqstream/unit-program.yaml From aa6a36a0062300d88fc0d6e6f959f4b322936c2f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 19:02:17 +0000 Subject: [PATCH 4/7] Convert system.md ASCII art diagram to Mermaid flowchart Agent-Logs-Url: https://github.com/demaconsulting/SarifMark/sessions/c0ec5818-3858-4c7c-b314-bdabee8c681e Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- docs/design/system.md | 45 +++++++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 21 deletions(-) diff --git a/docs/design/system.md b/docs/design/system.md index 048823b..648ced2 100644 --- a/docs/design/system.md +++ b/docs/design/system.md @@ -46,27 +46,30 @@ non-zero exit code without an unhandled-exception stack trace. ## Subsystem Interactions -```text -┌─────────────────────────────────────────────────────────┐ -│ Program (system entry point) │ -│ ┌──────────┐ creates ┌────────────────────────┐ │ -│ │ │──────────>│ Cli.Context │ │ -│ │ Main / │ │ (args, output, exit) │ │ -│ │ Run │ └────────────────────────┘ │ -│ │ │ calls ┌──────────────────────────┐ │ -│ │ │──────────>│ SelfTest.Validation.Run │ │ -│ │ │ └──────────────────────────┘ │ -│ │ │ calls ┌──────────────────────────┐ │ -│ │ │──────────>│ Sarif.SarifResults.Read │ │ -│ │ │ │ Sarif.SarifResults.ToMarkdown│ -│ └──────────┘ └──────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ - │ uses - ▼ - ┌──────────────────┐ - │ Utilities. │ - │ PathHelpers │ - └──────────────────┘ +```mermaid +flowchart TD + Main["Program\n(Main / Run)"] + + subgraph Cli + Context["Context\n(args, output, exit)"] + end + + subgraph SelfTest + Validation["Validation.Run"] + end + + subgraph Sarif + SarifResults["SarifResults.Read\nSarifResults.ToMarkdown"] + end + + subgraph Utilities + PathHelpers["PathHelpers"] + end + + Main -->|creates| Context + Main -->|calls| Validation + Main -->|calls| SarifResults + SelfTest -->|uses| PathHelpers ``` All subsystems receive a `Cli.Context` reference for output. The `Utilities` From c25e81f5546ac0515e5e26c905d480866d0e1a99 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 19:30:03 +0000 Subject: [PATCH 5/7] Fix broken children links in reqstream requirements files Agent-Logs-Url: https://github.com/demaconsulting/SarifMark/sessions/3af2c08c-35a2-4ee4-a57a-94ed9b6ff2ad Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- docs/reqstream/cli/subsystem-cli.yaml | 5 ----- docs/reqstream/sarif/subsystem-report.yaml | 2 -- docs/reqstream/sarif/subsystem-sarif.yaml | 4 ++-- docs/reqstream/sarifmark-system.yaml | 4 ++-- docs/reqstream/self-test/subsystem-self-test.yaml | 7 ++----- docs/reqstream/utilities/subsystem-utilities.yaml | 4 +++- 6 files changed, 9 insertions(+), 17 deletions(-) diff --git a/docs/reqstream/cli/subsystem-cli.yaml b/docs/reqstream/cli/subsystem-cli.yaml index f87da81..89eac9b 100644 --- a/docs/reqstream/cli/subsystem-cli.yaml +++ b/docs/reqstream/cli/subsystem-cli.yaml @@ -11,7 +11,6 @@ sections: making the tool suitable for DevOps workflows and batch processing scenarios. tags: [public] children: - - SarifMark-Program-Main - SarifMark-Context-Create tests: - IntegrationTest_VersionFlag_OutputsVersion @@ -24,7 +23,6 @@ sections: verification, and ensuring consistent behavior across different environments. tags: [public] children: - - SarifMark-Program-Version - SarifMark-Context-VersionFlag tests: - IntegrationTest_VersionFlag_OutputsVersion @@ -38,8 +36,6 @@ sections: tags: [public] children: - SarifMark-Context-HelpFlag - - SarifMark-Program-Banner - - SarifMark-Program-Help tests: - IntegrationTest_HelpFlag_OutputsUsageInformation - Context_Create_HelpFlag_SetsHelpTrue @@ -86,6 +82,5 @@ sections: tags: [public] children: - SarifMark-Context-UnknownArgs - - SarifMark-Program-Main-Exceptions tests: - IntegrationTest_UnknownArgument_ShowsError diff --git a/docs/reqstream/sarif/subsystem-report.yaml b/docs/reqstream/sarif/subsystem-report.yaml index 9e5dd9d..c24256a 100644 --- a/docs/reqstream/sarif/subsystem-report.yaml +++ b/docs/reqstream/sarif/subsystem-report.yaml @@ -23,7 +23,6 @@ sections: hierarchies, preventing heading level conflicts when reports are embedded in larger documents. tags: [public] children: - - SarifMark-Context-ReportDepthParam - SarifMark-SarifResults-ValidateDepth tests: - IntegrationTest_ReportDepth_IsConfigurable @@ -59,7 +58,6 @@ sections: conventions, improving consistency across project documentation. tags: [public] children: - - SarifMark-Context-HeadingParam - SarifMark-SarifResults-ToMarkdown tests: - SarifResults_ToMarkdown_CustomHeading_UsesProvidedHeading diff --git a/docs/reqstream/sarif/subsystem-sarif.yaml b/docs/reqstream/sarif/subsystem-sarif.yaml index 76b03ed..68f3fe0 100644 --- a/docs/reqstream/sarif/subsystem-sarif.yaml +++ b/docs/reqstream/sarif/subsystem-sarif.yaml @@ -93,7 +93,7 @@ sections: execution without proper input, improving tool safety and predictability. tags: [public] children: - - SarifMark-Program-SarifAnalysis + - SarifMark-SarifResults-ValidatePath tests: - IntegrationTest_MissingSarifParameter_ShowsError @@ -104,6 +104,6 @@ sections: fulfill its primary purpose of converting analysis results to markdown documentation. tags: [public] children: - - SarifMark-Program-SarifAnalysis + - SarifMark-SarifResults-ParseResults tests: - IntegrationTest_ValidSarifFile_ProcessesSuccessfully diff --git a/docs/reqstream/sarifmark-system.yaml b/docs/reqstream/sarifmark-system.yaml index a2b5256..e5be35b 100644 --- a/docs/reqstream/sarifmark-system.yaml +++ b/docs/reqstream/sarifmark-system.yaml @@ -40,7 +40,7 @@ sections: Reading and analyzing SARIF files is the core purpose of the tool, enabling integration with static analysis workflows. tests: - - IntegrationTest_SarifFile_ProcessesSarifFile + - IntegrationTest_ValidSarifFile_ProcessesSuccessfully - id: SarifMark-System-Report title: The tool shall generate markdown reports from SARIF files. @@ -48,7 +48,7 @@ sections: Markdown report generation makes SARIF analysis results accessible to stakeholders in a readable format. tests: - - IntegrationTest_ReportFile_GeneratesMarkdownReport + - IntegrationTest_GenerateReport_CreatesReportFile - id: SarifMark-System-Enforce title: The tool shall return non-zero exit code when enforcement mode detects issues. diff --git a/docs/reqstream/self-test/subsystem-self-test.yaml b/docs/reqstream/self-test/subsystem-self-test.yaml index dfa40f8..ea749b6 100644 --- a/docs/reqstream/self-test/subsystem-self-test.yaml +++ b/docs/reqstream/self-test/subsystem-self-test.yaml @@ -11,7 +11,6 @@ sections: environment, ensuring proper installation and configuration. tags: [public] children: - - SarifMark-Context-ValidateFlag - SarifMark-Validation-Run tests: - IntegrationTest_ValidateFlag_RunsSelfValidation @@ -59,8 +58,7 @@ sections: with analysis issues from being merged or deployed, thereby maintaining code quality standards. tags: [public] children: - - SarifMark-Context-EnforceFlag - - SarifMark-Program-SarifAnalysis + - SarifMark-Validation-EnforcementTest tests: - IntegrationTest_EnforceFlagWithIssues_ReturnsError - SarifMark_Enforcement @@ -72,8 +70,7 @@ sections: and preventing the progression of problematic code through deployment pipelines. tags: [public] children: - - SarifMark-Context-ExitCode - - SarifMark-Context-WriteError + - SarifMark-Validation-EnforcementTest tests: - IntegrationTest_EnforceFlagWithIssues_ReturnsError - SarifMark_Enforcement diff --git a/docs/reqstream/utilities/subsystem-utilities.yaml b/docs/reqstream/utilities/subsystem-utilities.yaml index b62c66a..52df4ea 100644 --- a/docs/reqstream/utilities/subsystem-utilities.yaml +++ b/docs/reqstream/utilities/subsystem-utilities.yaml @@ -13,6 +13,8 @@ sections: tags: [internal] children: - SarifMark-PathHelpers-SafeCombine - - SarifMark-PathHelpers-TraversalCheck + - SarifMark-PathHelpers-PreCombineCheck + - SarifMark-PathHelpers-RootedCheck + - SarifMark-PathHelpers-PostCombineCheck tests: - PathHelpers_SafePathCombine_ValidPaths_CombinesSuccessfully From 4ca61f33f7d28cc3eba54fc7c777de8aa0774b24 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 31 Mar 2026 16:06:47 -0400 Subject: [PATCH 6/7] Update docs/design/system.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/design/system.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/design/system.md b/docs/design/system.md index 648ced2..353b327 100644 --- a/docs/design/system.md +++ b/docs/design/system.md @@ -32,8 +32,11 @@ The system entry point is `Program.Main`. On every invocation it: 1. Returns `Context.ExitCode` to the shell (0 for success, 1 on error). `ArgumentException` and `InvalidOperationException` are caught at the -`Main` level and translated to exit code 1, so all error paths produce a -non-zero exit code without an unhandled-exception stack trace. +`Main` level and translated to exit code 1, so these expected error paths +produce a non-zero exit code without an unhandled-exception stack trace. Any +other unexpected `Exception` is logged with an "Unexpected error" message and +then rethrown, allowing the default .NET unhandled-exception behavior (stack +trace and process termination with a non-zero exit code) to occur. `Program.Run` evaluates conditions in priority order: From 3dd692014264debf03728cd2846cfec19e27fbb2 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 31 Mar 2026 16:07:19 -0400 Subject: [PATCH 7/7] Update docs/design/system.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/design/system.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/design/system.md b/docs/design/system.md index 353b327..16c8286 100644 --- a/docs/design/system.md +++ b/docs/design/system.md @@ -38,14 +38,16 @@ other unexpected `Exception` is logged with an "Unexpected error" message and then rethrown, allowing the default .NET unhandled-exception behavior (stack trace and process termination with a non-zero exit code) to occur. -`Program.Run` evaluates conditions in priority order: - -| Mode | Condition | Subsystem Invoked | -|------------|------------------------|--------------------------------------------| -| Version | `--version` flag | None (prints version string) | -| Help | `--help` flag | None (prints usage) | -| Validate | `--validate` flag | `SelfTest.Validation.Run` | -| Analysis | *(default)* | `Sarif.SarifResults.Read` + `ToMarkdown` | +`Program.Run` first prints the standard banner for all non-`--version` +invocations, then evaluates conditions in priority order: + +| Mode | Condition | Subsystem Invoked | +|------------|--------------------------------------------|--------------------------------------------| +| Banner | Any non-`--version` invocation (first) | `Program` (prints standard banner) | +| Version | `--version` flag | None (prints version string) | +| Help | `--help` flag | None (prints usage) | +| Validate | `--validate` flag | `SelfTest.Validation.Run` | +| Analysis | *(default)* | `Sarif.SarifResults.Read` + `ToMarkdown` | ## Subsystem Interactions