Rewrite subsystem tests to exercise subsystem units directly

docs/design/sarifmark/cli/cli.md

@@ -23,12 +23,29 @@ The `Cli` subsystem contains the following software unit:
 
 The `Cli` subsystem exposes the following interface to the rest of the tool:
 
+**Methods:**
+
 | 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.    |
+
+**Parsed flags and parameters** (set by `Create`, read by the application layer):
+
+| Property      | Type      | CLI flag(s)              | Description                                   |
+|---------------|-----------|--------------------------|-----------------------------------------------|
+| `Version`     | `bool`    | `-v`, `--version`        | Version query flag                            |
+| `Help`        | `bool`    | `-?`, `-h`, `--help`     | Help flag                                     |
+| `Silent`      | `bool`    | `--silent`               | Suppress console output flag                  |
+| `Validate`    | `bool`    | `--validate`             | Self-validation mode flag                     |
+| `Enforce`     | `bool`    | `--enforce`              | Enforcement mode flag                         |
+| `SarifFile`   | `string?` | `--sarif <file>`         | Path to the SARIF input file                  |
+| `ReportFile`  | `string?` | `--report <file>`        | Path for the markdown report output file      |
+| `ReportDepth` | `int`     | `--report-depth <depth>` | Markdown heading depth for the report         |
+| `Heading`     | `string?` | `--heading <text>`       | Custom heading text for the report            |
+| `ResultsFile` | `string?` | `--results <file>`       | Path for the self-validation results file     |
+| `ExitCode`    | `int`     | *(derived)*              | 0 until `WriteError` is called, then 1        |
 
 ## Interactions
 

docs/design/sarifmark/sarif/sarif.md

@@ -8,7 +8,7 @@ markdown reports from the extracted results. It consists of two records:
 `SarifResults` (the full results collection with reading and reporting
 logic). This layer satisfies requirements `SarifMark-Sarif-Reading`,
 `SarifMark-Sarif-Validation`, `SarifMark-Sarif-ToolInfo`, `SarifMark-Sarif-Results`,
-`SarifMark-Sarif-Locations`, `SarifMark-Sarif-FilePaths`, `SarifMark-Sarif-Required`,
+`SarifMark-Sarif-Locations`, `SarifMark-Sarif-FilePaths`,
 `SarifMark-Sarif-Processing`, `SarifMark-Report-Markdown`, `SarifMark-Report-Depth`,
 `SarifMark-Report-Counts`, `SarifMark-Report-Locations`, `SarifMark-Report-Headings`, and
 `SarifMark-Report-LineBreaks`.
@@ -51,10 +51,10 @@ formats each result with location information and result counts. This satisfies
 
 ## CLI Integration
 
-The requirement `SarifMark-Sarif-Required` (the tool shall require the `--sarif` parameter
-for analysis) is enforced at the command-line layer rather than within this library. The
+The requirement `SarifMark-System-SarifRequired` (the tool shall require the `--sarif` parameter
+for analysis) is enforced at the application layer rather than within this library. The
 `ProcessSarifAnalysis` method in `Program.cs` validates that `--sarif` is provided before
-invoking the SARIF reading layer. See the Command Line document for full details.
+invoking the SARIF reading layer. See the Program Class document for full details.
 
 ## Class Details
 

docs/reqstream/sarifmark/cli/cli.yaml

@@ -2,44 +2,44 @@
 sections:
   - title: SarifMark Requirements
     sections:
-      - title: Command-Line Interface
+      - title: CLI Subsystem
         requirements:
           - id: SarifMark-Cli-Interface
-            title: The tool shall provide a command-line interface.
+            title: The CLI subsystem shall accept command-line arguments and route output.
             justification: >-
               A command-line interface enables automation, scripting, and integration into CI/CD pipelines,
               making the tool suitable for DevOps workflows and batch processing scenarios.
             tags: [public]
             children:
               - SarifMark-Context-Create
             tests:
-              - Cli_VersionFlag_OutputsVersion
-              - Cli_HelpFlag_OutputsUsageInformation
+              - Cli_VersionFlag_SetsVersionFlag
+              - Cli_HelpFlag_SetsHelpFlag
 
           - id: SarifMark-Cli-Version
-            title: The tool shall display version information when requested.
+            title: The CLI shall recognize the --version flag.
             justification: >-
-              Version information allows users to identify the tool version for troubleshooting, compatibility
-              verification, and ensuring consistent behavior across different environments.
+              Recognizing the version flag allows the application layer to identify the requested operation
+              and display the tool version, supporting troubleshooting and compatibility verification.
             tags: [public]
             children:
               - SarifMark-Context-VersionFlag
             tests:
-              - Cli_VersionFlag_OutputsVersion
+              - Cli_VersionFlag_SetsVersionFlag
 
           - id: SarifMark-Cli-Help
-            title: The tool shall display help information when requested.
+            title: The CLI shall recognize the --help flag.
             justification: >-
-              Help information improves discoverability and usability by providing users with guidance on
-              available options, parameters, and usage patterns without consulting external documentation.
+              Recognizing the help flag allows the application layer to display usage information,
+              improving discoverability without consulting external documentation.
             tags: [public]
             children:
               - SarifMark-Context-HelpFlag
             tests:
-              - Cli_HelpFlag_OutputsUsageInformation
+              - Cli_HelpFlag_SetsHelpFlag
 
           - id: SarifMark-Cli-Silent
-            title: The tool shall support silent mode to suppress console output.
+            title: The CLI shall suppress console output when the silent flag is set.
             justification: >-
               Silent mode enables cleaner integration into automated workflows and CI/CD pipelines where console
               noise needs to be minimized, while still allowing log files to capture detailed information.
@@ -50,7 +50,7 @@ sections:
               - Cli_SilentFlag_SuppressesOutput
 
           - id: SarifMark-Cli-Log
-            title: The tool shall support writing output to a log file.
+            title: The CLI shall write output to a log file when the log parameter is set.
             justification: >-
               Log file support enables persistent record-keeping, debugging, and audit trails, especially valuable
               in automated environments where console output may not be readily available.
@@ -61,23 +61,101 @@ sections:
               - Cli_LogFile_WritesOutputToFile
 
           - id: SarifMark-Cli-Enforce
-            title: The tool shall support enforcing quality gate checks.
+            title: The CLI shall recognize the --enforce flag.
             justification: >-
-              Quality gate enforcement enables the tool to act as a quality gate in CI/CD pipelines, failing
-              builds when issues are detected and ensuring code quality standards are maintained.
+              Recognizing the enforce flag allows the application layer to determine whether to apply
+              quality gate behavior, making it suitable for integration into CI/CD pipelines.
             tags: [public]
             children:
               - SarifMark-Context-EnforceFlag
             tests:
-              - Cli_EnforceFlagWithIssues_ReturnsError
+              - Cli_EnforceFlag_SetsEnforceFlag
+
+          - id: SarifMark-Cli-WriteError
+            title: The CLI shall write errors to stderr and set a non-zero exit code.
+            justification: >-
+              Writing errors to stderr separates diagnostic output from the regular output stream, and
+              automatically setting a non-zero exit code ensures that callers receive a failure signal
+              without requiring explicit exit code management throughout the codebase.
+            tags: [public]
+            children:
+              - SarifMark-Context-WriteError
+            tests:
+              - Cli_WriteError_SetsExitCodeToOne
 
           - id: SarifMark-Cli-InvalidArgs
-            title: The tool shall reject unknown command-line arguments.
+            title: The CLI shall reject unknown command-line arguments.
             justification: >-
               Rejecting unknown arguments prevents silent failures from typos or incorrect parameters, ensuring
               users receive immediate feedback about misconfigured commands.
             tags: [public]
             children:
               - SarifMark-Context-UnknownArgs
             tests:
-              - Cli_UnknownArgument_ShowsError
+              - Cli_UnknownArgument_ThrowsArgumentException
+
+          - id: SarifMark-Cli-Validate
+            title: The CLI shall recognize the --validate flag.
+            justification: >-
+              Recognizing the validate flag allows the application layer to activate self-validation mode,
+              enabling verification that the tool operates correctly in the deployment environment.
+            tags: [public]
+            children:
+              - SarifMark-Context-ValidateFlag
+            tests:
+              - Cli_ValidateFlag_SetsValidateFlag
+
+          - id: SarifMark-Cli-Sarif
+            title: The CLI shall accept a SARIF file path via the --sarif parameter.
+            justification: >-
+              Exposing a dedicated SARIF file path parameter gives the application layer a clean, named value
+              that decouples argument parsing from file processing.
+            tags: [public]
+            children:
+              - SarifMark-Context-SarifParam
+            tests:
+              - Cli_SarifParameter_SetsSarifFilePath
+
+          - id: SarifMark-Cli-Report
+            title: The CLI shall accept a report file path via the --report parameter.
+            justification: >-
+              A dedicated report file path parameter gives the application layer a clear output target,
+              keeping argument parsing separate from report generation logic.
+            tags: [public]
+            children:
+              - SarifMark-Context-ReportParam
+            tests:
+              - Cli_ReportParameter_SetsReportFilePath
+
+          - id: SarifMark-Cli-ReportDepth
+            title: The CLI shall accept a heading depth via the --report-depth parameter.
+            justification: >-
+              Exposing a validated heading depth parameter allows the application layer to control markdown
+              report heading levels without reimplementing argument parsing or range checking.
+            tags: [public]
+            children:
+              - SarifMark-Context-ReportDepthParam
+            tests:
+              - Cli_ReportDepthParameter_SetsReportDepth
+
+          - id: SarifMark-Cli-Heading
+            title: The CLI shall accept a custom heading via the --heading parameter.
+            justification: >-
+              Exposing a custom heading parameter lets the application layer pass user-specified titles
+              directly to the report formatter, keeping argument handling separate from output logic.
+            tags: [public]
+            children:
+              - SarifMark-Context-HeadingParam
+            tests:
+              - Cli_HeadingParameter_SetsCustomHeading
+
+          - id: SarifMark-Cli-Results
+            title: The CLI shall accept a results file path via the --results parameter.
+            justification: >-
+              A dedicated results file path parameter gives the application layer a clear destination for
+              test result output during self-validation, keeping argument parsing separate from output logic.
+            tags: [public]
+            children:
+              - SarifMark-Context-ResultsParam
+            tests:
+              - Cli_ResultsParameter_SetsResultsFilePath

docs/reqstream/sarifmark/sarif/report.yaml

@@ -13,7 +13,7 @@ sections:
             children:
               - SarifMark-SarifResults-ToMarkdown
             tests:
-              - Sarif_GenerateReport_CreatesReportFile
+              - Sarif_GenerateReport_ProducesMarkdownContent
 
           - id: SarifMark-Report-Depth
             title: The tool shall support configurable markdown heading depth.

docs/reqstream/sarifmark/sarif/sarif.yaml

@@ -25,8 +25,8 @@ sections:
               - SarifMark-SarifResults-ValidatePath
               - SarifMark-SarifResults-ValidateStructure
             tests:
-              - Sarif_NonExistentSarifFile_ShowsError
-              - Sarif_InvalidSarifFile_ShowsFormatError
+              - Sarif_NonExistentSarifFile_ThrowsFileNotFoundException
+              - Sarif_InvalidSarifFile_ThrowsInvalidOperationException
 
           - id: SarifMark-Sarif-ToolInfo
             title: The tool shall extract tool information from SARIF files.
@@ -65,27 +65,15 @@ sections:
               - Sarif_Report_ContainsLocationInfo
 
           - id: SarifMark-Sarif-FilePaths
-            title: The tool shall require valid file paths for SARIF input.
+            title: The SARIF subsystem shall require valid file paths for SARIF input.
             justification: >-
               Path validation ensures clear error messages when files are missing or incorrectly specified,
               improving user experience and preventing confusing runtime failures.
             tags: [public]
             children:
               - SarifMark-SarifResults-ValidatePath
             tests:
-              - Sarif_MissingSarifParameter_ShowsError
-              - Sarif_NonExistentSarifFile_ShowsError
-
-          - id: SarifMark-Sarif-Required
-            title: The tool shall require the --sarif parameter for analysis.
-            justification: >-
-              Requiring explicit SARIF file specification ensures intentional operation and prevents accidental
-              execution without proper input, improving tool safety and predictability.
-            tags: [public]
-            children:
-              - SarifMark-SarifResults-ValidatePath
-            tests:
-              - Sarif_MissingSarifParameter_ShowsError
+              - Sarif_NonExistentSarifFile_ThrowsFileNotFoundException
 
           - id: SarifMark-Sarif-Processing
             title: The tool shall process valid SARIF files successfully.

docs/reqstream/sarifmark/sarifmark.yaml

@@ -37,6 +37,17 @@ sections:
         tests:
           - IntegrationTest_ValidateFlag_RunsSelfValidation
 
+      - id: SarifMark-System-SarifRequired
+        title: The tool shall require the --sarif parameter for SARIF analysis.
+        tags: [public]
+        justification: >-
+          Requiring explicit SARIF file specification ensures intentional operation and prevents
+          accidental execution without proper input, improving tool safety and predictability.
+        children:
+          - SarifMark-Sarif-FilePaths
+        tests:
+          - IntegrationTest_MissingSarifParameter_ShowsError
+
       - id: SarifMark-System-SarifAnalysis
         title: The tool shall read and analyze SARIF files.
         tags: [public]

docs/reqstream/sarifmark/self-test/self-test.yaml

@@ -60,7 +60,7 @@ sections:
             children:
               - SarifMark-Validation-EnforcementTest
             tests:
-              - SelfTest_EnforceFlag_ReturnsNonZeroOnIssues
+              - SelfTest_EnforcementTest_RunsWithinValidation
 
           - id: SarifMark-Enforce-ExitCode
             title: The tool shall return non-zero exit code when issues found in enforcement mode.
@@ -71,4 +71,4 @@ sections:
             children:
               - SarifMark-Validation-EnforcementTest
             tests:
-              - SelfTest_EnforceFlag_ReturnsNonZeroOnIssues
+              - SelfTest_EnforcementTest_RunsWithinValidation