Fix duplicate link references and address all reviewmark review-set findings

.reviewmark.yaml

@@ -32,6 +32,8 @@ reviews:
       - "docs/reqstream/context.yaml"
       - "docs/design/introduction.md"
       - "docs/design/command-line.md"
+      - "docs/design/program.md"
+      - "docs/design/context.md"
       - "src/**/Program.cs"
       - "src/**/Context.cs"
       - "test/**/ProgramTests.cs"
@@ -58,6 +60,7 @@ reviews:
       - "docs/reqstream/report.yaml"
       - "docs/reqstream/sarif-results.yaml"
       - "docs/design/sarif.md"
+      - "docs/design/sarif-results.md"
       - "src/**/SarifResults.cs"
       - "test/**/SarifResultsTests.cs"
       - "test/**/IntegrationTests.cs"
@@ -129,7 +132,6 @@ reviews:
     title: Review of SarifMark PathHelpers Software Unit
     paths:
       - "docs/reqstream/path-helpers.yaml"
-      - "docs/design/utilities.md"
       - "docs/design/path-helpers.md"
       - "src/**/PathHelpers.cs"
       - "test/**/PathHelpersTests.cs"

docs/design/definition.yaml

@@ -7,7 +7,6 @@ input-files:
   - docs/design/introduction.md
   - docs/design/command-line.md
   - docs/design/sarif.md
-  - docs/design/utilities.md
   - docs/design/validation.md
   - docs/design/program.md
   - docs/design/context.md

docs/design/introduction.md

@@ -15,13 +15,12 @@ The purpose of this document is to:
 
 ## Scope
 
-This document covers the design of four primary functional layers within SarifMark:
+This document covers the design of three primary functional layers within SarifMark:
 
 - The **command-line layer**: the `Program` entry point and `Context` class that handle
   argument parsing, output routing, and program flow control
 - The **SARIF and reporting layer**: the `SarifResult` and `SarifResults` classes that
   read SARIF files and generate markdown reports
-- The **utilities layer**: the `PathHelpers` class providing safe path operations
 - The **self-validation layer**: the `Validation` class that provides built-in
   verification of the tool's core functionality
 
@@ -30,8 +29,7 @@ architecture, and the requirements it satisfies — followed by **class-level do
 that describe each implementing class in detail.
 
 This document does not cover installation, end-user usage patterns, or the CI/CD pipeline
-configuration. Those topics are addressed in the [User Guide][user-guide] and the
-[Requirements document][requirements-doc].
+configuration. Those topics are addressed in other [SarifMark repository][sarifmark-repo] documentation.
 
 ## Audience
 
@@ -55,5 +53,4 @@ This document describes the intent and structure of that code; any discrepancy b
 this document and the code should be resolved by updating this document to reflect the
 actual implementation, or by raising a defect against the code.
 
-[user-guide]: https://github.com/demaconsulting/SarifMark
-[requirements-doc]: https://github.com/demaconsulting/SarifMark
+[sarifmark-repo]: https://github.com/demaconsulting/SarifMark

docs/design/program.md

@@ -9,7 +9,7 @@ appropriate subsystem, and handles top-level exception translation.
 ## Version Property
 
 The static `Version` property reads the assembly's `AssemblyInformationalVersionAttribute` at
-runtime. If that attribute is absent it falls back to the `AssemblyVersion`; if that is also
+runtime. If that attribute is absent, it falls back to the `AssemblyVersion`; if that is also
 unavailable it returns `"0.0.0"`. This satisfies requirement `SarifMark-Program-Version`.
 
 ## Main Method

docs/design/sarif-results.md

@@ -93,7 +93,8 @@ and `SarifMark-SarifResults-FilterSuppressions`.
    The sub-heading level is `min(depth + 1, 6)`.
 3. **Issues section** — calls `AppendIssuesSection` to emit the `Issues` sub-heading, the
    result count formatted by `FormatFoundText`, and one line per result formatted by
-   `FormatLocation`.
+   `FormatLocation`. Each result line is appended with a trailing two-space markdown hard
+   line break (`  `) before the newline, satisfying requirement `SarifMark-Report-LineBreaks`.
 
 This satisfies requirement `SarifMark-SarifResults-ToMarkdown`.
 

docs/design/validation.md

@@ -14,7 +14,11 @@ organizes all test execution internally.
 
 ### Run Method
 
-`Run` orchestrates the self-validation sequence:
+Before executing the sequence, `Run` validates its input by calling
+`ArgumentNullException.ThrowIfNull(context)`, throwing `ArgumentNullException` immediately if
+`context` is null. This satisfies requirement `SarifMark-Validation-NullCheck`.
+
+`Run` then orchestrates the self-validation sequence:
 
 1. Calls `PrintValidationHeader` to emit a markdown table with tool version, machine
    name, OS version, .NET runtime, and timestamp.
@@ -52,14 +56,11 @@ The test name is `SarifMark_MarkdownReportGeneration`, satisfying `SarifMark-Rep
 
 ### RunEnforcementTest
 
-`RunEnforcementTest` verifies enforcement mode:
+`RunEnforcementTest` verifies enforcement mode by delegating to `RunValidationTest` with
+`--enforce` as an extra argument and a validator that:
 
-1. Creates a `TemporaryDirectory`.
-2. Writes the mock SARIF file.
-3. Constructs a `Context` with `--silent`, `--log <file>`, `--sarif <file>`, and
-   `--enforce`.
-4. Calls `Program.Run` and verifies exit code is non-zero.
-5. Checks the log contains `"Error: Issues found in SARIF file"`.
+1. Verifies exit code is non-zero.
+2. Checks the log contains `"Error: Issues found in SARIF file"`.
 
 The test name is `SarifMark_Enforcement`, satisfying `SarifMark-Enforce-Mode` and
 `SarifMark-Enforce-ExitCode`.
@@ -68,15 +69,16 @@ The test name is `SarifMark_Enforcement`, satisfying `SarifMark-Enforce-Mode` an
 
 `RunValidationTest` is a private shared helper used by `RunSarifReadingTest`,
 `RunMarkdownReportGenerationTest`, and `RunEnforcementTest`. It accepts a test name, an
-optional report file name, and a caller-supplied `validator` function, and:
+optional report file name, a caller-supplied `validator` function, and an optional
+`extraArgs` collection, and:
 
 1. Creates a `TemporaryDirectory`.
 2. Creates a mock SARIF file and builds a command-line argument list with `--silent`,
    `--log`, and `--sarif`. If a `reportFileName` is provided, adds `--report` to the
-   argument list.
+   argument list. Any `extraArgs` are appended last.
 3. Constructs a `Context` and calls `Program.Run`, capturing the exit code.
-4. Reads the log and (if present) report file contents and passes them to the `validator`
-   function.
+4. Reads the log and (if present) report file contents and passes the exit code, log
+   content, and report content to the `validator` function.
 5. Records the test as passed or failed in the `TestResults` collection and prints a `✓`
    or `✗` status line to the context output.
 

docs/reqstream/context.yaml

@@ -150,6 +150,8 @@ sections:
             tests:
               - Context_WriteLine_WritesToConsole
               - Context_WriteLine_SilentMode_DoesNotWriteToConsole
+              - Context_WriteLine_WithLogFile_WritesToLog
+              - Context_WriteLine_SilentModeWithLogFile_WritesToLog
 
           - id: SarifMark-Context-WriteError
             title: >-
@@ -163,6 +165,7 @@ sections:
             tests:
               - Context_WriteError_WritesToErrorAndSetsExitCode
               - Context_WriteError_SilentMode_DoesNotWriteToConsoleButSetsExitCode
+              - Context_WriteError_WithLogFile_WritesToLog
 
           - id: SarifMark-Context-ExitCode
             title: The ExitCode property shall start at zero and change to one after the first call to WriteError.

docs/reqstream/platform.yaml

@@ -77,8 +77,8 @@ sections:
           - id: SarifMark-Plt-Net10
             title: The tool shall support .NET 10.0 runtime.
             justification: >-
-              .NET 10.0 support provides forward compatibility and ensures the tool remains viable as users adopt
-              future .NET versions, extending the tool's lifespan and relevance.
+              .NET 10.0 support provides forward compatibility and ensures the tool remains viable as
+              adoption grows, extending the tool's lifespan and relevance.
             tags: [public]
             tests:
               - dotnet10.x@SarifMark_SarifReading

docs/reqstream/program.yaml

@@ -76,3 +76,6 @@ sections:
             tags: [internal]
             tests:
               - Program_Main_NoArguments_ReturnsError
+              - IntegrationTest_ValidSarifFile_ProcessesSuccessfully
+              - IntegrationTest_EnforceFlagWithIssues_ReturnsError
+              - IntegrationTest_GenerateReport_CreatesReportFile

docs/reqstream/sarif-results.yaml

@@ -13,6 +13,7 @@ sections:
             tags: [internal]
             tests:
               - SarifResults_Read_NoResults_ReturnsValidResults
+              - SarifResults_InternalConstructor_CreatesValidInstance
 
           - id: SarifMark-SarifResults-ValidatePath
             title: The Read method shall validate the file path is non-null, non-empty, and the file exists.
@@ -139,3 +140,4 @@ sections:
             tests:
               - SarifResults_ToMarkdown_NoResults_ShowsFoundNoResults
               - SarifResults_ToMarkdown_OneResult_UsesSingularForm
+              - SarifResults_ToMarkdown_Depth1_ProducesCorrectOutput

src/DemaConsulting.SarifMark/SarifResult.cs

@@ -51,7 +51,7 @@ public record SarifResult
     public int? StartLine { get; }
 
     /// <summary>
-    ///     Internal constructor for testing purposes.
+    ///     Internal constructor to enforce that instances are only created through the validated parsing pipeline.
     /// </summary>
     /// <param name="ruleId">The rule identifier.</param>
     /// <param name="level">The level of the result.</param>

src/DemaConsulting.SarifMark/SarifResults.cs

@@ -49,7 +49,7 @@ public record SarifResults
     public int ResultCount => Results.Count;
 
     /// <summary>
-    ///     Internal constructor for testing purposes.
+    ///     Internal constructor to enforce that instances are only created through the validated parsing pipeline.
     /// </summary>
     /// <param name="toolName">The name of the analysis tool.</param>
     /// <param name="toolVersion">The version of the analysis tool.</param>
@@ -117,13 +117,13 @@ private static JsonElement ValidateSarifStructure(JsonElement root)
             throw new InvalidOperationException("Invalid SARIF file: missing or invalid 'runs' array.");
         }
 
-        var runs = runsElement.EnumerateArray();
-        if (!runs.Any())
+        var runsEnumerator = runsElement.EnumerateArray();
+        if (!runsEnumerator.MoveNext())
         {
             throw new InvalidOperationException("Invalid SARIF file: 'runs' array is empty.");
         }
 
-        return runs.First();
+        return runsEnumerator.Current;
     }
 
     /// <summary>