refactor: Reorganize source into subsystem folders/namespaces

.cspell.yaml

@@ -67,6 +67,8 @@ words:
   - Sarif
   - SarifMark
   - SBOM
+  - selftest
+  - SelfTest
   - Semgrep
   - semver
   - slnx

.reviewmark.yaml

@@ -33,58 +33,20 @@ reviews:
     title: VersionMark Design Document Review
     paths:
       - "docs/reqstream/versionmark-system.yaml"
-      - "docs/design/introduction.md"
-      - "docs/design/system.md"
-      - "docs/design/subsystem-command-line.md"
-      - "docs/design/unit-program.md"
-      - "docs/design/unit-context.md"
-      - "docs/design/subsystem-configuration.md"
-      - "docs/design/unit-tool-config.md"
-      - "docs/design/unit-version-mark-config.md"
-      - "docs/design/subsystem-capture.md"
-      - "docs/design/unit-version-info.md"
-      - "docs/design/subsystem-publish.md"
-      - "docs/design/unit-markdown-formatter.md"
-      - "docs/design/subsystem-lint.md"
-      - "docs/design/unit-lint.md"
-      - "docs/design/subsystem-validation.md"
-      - "docs/design/unit-validation.md"
-      - "docs/design/unit-path-helpers.md"
+      - "docs/design/**/*.md"
 
   - id: VersionMark-AllRequirements
     title: VersionMark All Requirements Review
     paths:
       - "requirements.yaml"
-      - "docs/reqstream/versionmark-system.yaml"
-      - "docs/reqstream/platform-requirements.yaml"
-      - "docs/reqstream/subsystem-command-line.yaml"
-      - "docs/reqstream/unit-program.yaml"
-      - "docs/reqstream/unit-context.yaml"
-      - "docs/reqstream/subsystem-configuration.yaml"
-      - "docs/reqstream/unit-version-mark-config.yaml"
-      - "docs/reqstream/unit-tool-config.yaml"
-      - "docs/reqstream/subsystem-capture.yaml"
-      - "docs/reqstream/unit-version-info.yaml"
-      - "docs/reqstream/subsystem-publish.yaml"
-      - "docs/reqstream/unit-formatter.yaml"
-      - "docs/reqstream/subsystem-lint.yaml"
-      - "docs/reqstream/unit-lint.yaml"
-      - "docs/reqstream/subsystem-validation.yaml"
-      - "docs/reqstream/unit-validation.yaml"
-      - "docs/reqstream/unit-path-helpers.yaml"
-      - "docs/reqstream/ots-mstest.yaml"
-      - "docs/reqstream/ots-reqstream.yaml"
-      - "docs/reqstream/ots-buildmark.yaml"
-      - "docs/reqstream/ots-sarifmark.yaml"
-      - "docs/reqstream/ots-sonarmark.yaml"
-      - "docs/reqstream/ots-reviewmark.yaml"
-
-  # Command-Line Interface Subsystem
-  - id: VersionMark-CommandLine-Subsystem
-    title: Review of Command-Line Interface Subsystem
-    paths:
-      - "docs/reqstream/subsystem-command-line.yaml"
-      - "docs/design/subsystem-command-line.md"
+      - "docs/reqstream/**/*.yaml"
+
+  # Cli Subsystem
+  - id: VersionMark-Cli-Subsystem
+    title: Review of Cli Subsystem
+    paths:
+      - "docs/reqstream/subsystem-cli.yaml"
+      - "docs/design/subsystem-cli.md"
       - "test/**/ProgramTests.cs"
       - "test/**/ContextTests.cs"
       - "test/**/IntegrationTests.cs"
@@ -146,12 +108,12 @@ reviews:
       - "src/**/VersionInfo.cs"
       - "test/**/VersionInfoTests.cs"
 
-  # Publish Subsystem
-  - id: VersionMark-Publish-Subsystem
-    title: Review of Publish Subsystem
+  # Publishing Subsystem
+  - id: VersionMark-Publishing-Subsystem
+    title: Review of Publishing Subsystem
     paths:
-      - "docs/reqstream/subsystem-publish.yaml"
-      - "docs/design/subsystem-publish.md"
+      - "docs/reqstream/subsystem-publishing.yaml"
+      - "docs/design/subsystem-publishing.md"
       - "test/**/MarkdownFormatterTests.cs"
 
   - id: VersionMark-MarkdownFormatter-Review
@@ -162,12 +124,12 @@ reviews:
       - "src/**/MarkdownFormatter.cs"
       - "test/**/MarkdownFormatterTests.cs"
 
-  # Lint Subsystem
-  - id: VersionMark-Lint-Subsystem
-    title: Review of Lint Subsystem
+  # Linting Subsystem
+  - id: VersionMark-Linting-Subsystem
+    title: Review of Linting Subsystem
     paths:
-      - "docs/reqstream/subsystem-lint.yaml"
-      - "docs/design/subsystem-lint.md"
+      - "docs/reqstream/subsystem-linting.yaml"
+      - "docs/design/subsystem-linting.md"
       - "test/**/LintTests.cs"
 
   - id: VersionMark-Lint-Review
@@ -178,12 +140,12 @@ reviews:
       - "src/**/Lint.cs"
       - "test/**/LintTests.cs"
 
-  # Validation Subsystem
-  - id: VersionMark-Validation-Subsystem
-    title: Review of Validation Subsystem
+  # SelfTest Subsystem
+  - id: VersionMark-SelfTest-Subsystem
+    title: Review of SelfTest Subsystem
     paths:
-      - "docs/reqstream/subsystem-validation.yaml"
-      - "docs/design/subsystem-validation.md"
+      - "docs/reqstream/subsystem-selftest.yaml"
+      - "docs/design/subsystem-selftest.md"
 
   - id: VersionMark-Validation-Review
     title: Review of Validation Unit

docs/design/definition.yaml

@@ -6,19 +6,19 @@ input-files:
   - docs/design/title.txt
   - docs/design/introduction.md
   - docs/design/system.md
-  - docs/design/subsystem-command-line.md
+  - docs/design/subsystem-cli.md
   - docs/design/unit-program.md
   - docs/design/unit-context.md
   - docs/design/subsystem-configuration.md
   - docs/design/unit-tool-config.md
   - docs/design/unit-version-mark-config.md
   - docs/design/subsystem-capture.md
   - docs/design/unit-version-info.md
-  - docs/design/subsystem-publish.md
+  - docs/design/subsystem-publishing.md
   - docs/design/unit-markdown-formatter.md
-  - docs/design/subsystem-lint.md
+  - docs/design/subsystem-linting.md
   - docs/design/unit-lint.md
-  - docs/design/subsystem-validation.md
+  - docs/design/subsystem-selftest.md
   - docs/design/unit-validation.md
   - docs/design/unit-path-helpers.md
 template: template.html

docs/design/introduction.md

@@ -17,17 +17,17 @@ The purpose of this document is to:
 
 This document covers the design of six subsystems within VersionMark:
 
-- The **Command-Line Interface Subsystem**: the `Program` entry point and `Context` class
+- The **Cli Subsystem**: the `Program` entry point and `Context` class
   that handle argument parsing, output routing, and program flow control
 - The **Configuration Subsystem**: the `VersionMarkConfig` and `ToolConfig` classes that
   read and interpret `.versionmark.yaml` configuration files
 - The **Capture Subsystem**: the `VersionInfo` record that serializes and deserializes
   captured version data to and from JSON
-- The **Publish Subsystem**: the `MarkdownFormatter` class that generates the markdown
+- The **Publishing Subsystem**: the `MarkdownFormatter` class that generates the markdown
   version report from captured data
-- The **Lint Subsystem**: the `Lint` class that validates `.versionmark.yaml` configuration
+- The **Linting Subsystem**: the `Lint` class that validates `.versionmark.yaml` configuration
   files and reports issues with precise source locations
-- The **Validation Subsystem**: the `Validation` class and `PathHelpers` utility that
+- The **SelfTest Subsystem**: the `Validation` class and `PathHelpers` utility that
   together provide built-in verification of the tool's core functionality
 
 This document does not cover installation, end-user usage patterns, or the CI/CD pipeline
@@ -41,23 +41,47 @@ software units, with a short description of each node's role.
 
 ```text
 VersionMark (Software System)               Version capture/publish tool
-├── Command-Line Interface Subsystem        Argument parsing and dispatch
+├── Cli Subsystem                           Argument parsing and dispatch
 │   ├── Program (Software Unit)             Tool entry point
 │   └── Context (Software Unit)             Command-line state container
 ├── Configuration Subsystem                 YAML configuration loading
 │   ├── VersionMarkConfig (Software Unit)   Top-level config container
 │   └── ToolConfig (Software Unit)          Per-tool config record
 ├── Capture Subsystem                       Tool version capture
 │   └── VersionInfo (Software Unit)         JSON version data record
-├── Publish Subsystem                       Markdown report publishing
+├── Publishing Subsystem                    Markdown report publishing
 │   └── MarkdownFormatter (Software Unit)   Version report formatter
-├── Lint Subsystem                          Configuration file lint
+├── Linting Subsystem                       Configuration file lint
 │   └── Lint (Software Unit)                YAML configuration validator
-└── Validation Subsystem                    Built-in self-validation
+└── SelfTest Subsystem                      Built-in self-validation
     ├── Validation (Software Unit)          Self-validation runner
     └── PathHelpers (Software Unit)         Safe path combination
 ```
 
+## Folder Layout
+
+The source files are arranged in subsystem-aligned subdirectories beneath the main project
+folder. Each directory corresponds to one subsystem described above, making it
+straightforward to locate the implementation for any given component.
+
+```text
+src/DemaConsulting.VersionMark/
+├── Program.cs                          — entry point and execution orchestrator
+├── Cli/
+│   └── Context.cs                      — command-line argument parser and I/O owner
+├── Configuration/
+│   └── VersionMarkConfig.cs            — YAML configuration and tool definitions
+├── Capture/
+│   └── VersionInfo.cs                  — captured version data record
+├── Publishing/
+│   └── MarkdownFormatter.cs            — markdown report generation
+├── Linting/
+│   └── Lint.cs                         — YAML configuration linter
+└── SelfTest/
+    ├── Validation.cs                   — self-validation test runner
+    └── PathHelpers.cs                  — safe path utilities
+```
+
 ## Audience
 
 This document is intended for:

docs/design/subsystem-command-line.md → docs/design/subsystem-cli.md

@@ -1,4 +1,4 @@
-# Command-Line Interface Subsystem
+# Cli Subsystem
 
 ## Overview
 

docs/design/subsystem-lint.md → docs/design/subsystem-linting.md

@@ -1,4 +1,4 @@
-# Lint Subsystem
+# Linting Subsystem
 
 ## Overview
 

docs/design/subsystem-publish.md → docs/design/subsystem-publishing.md

@@ -1,4 +1,4 @@
-# Publish Subsystem
+# Publishing Subsystem
 
 ## Overview
 

docs/design/subsystem-validation.md → docs/design/subsystem-selftest.md

@@ -1,4 +1,4 @@
-# Validation Subsystem
+# SelfTest Subsystem
 
 ## Overview
 

docs/design/system.md

@@ -46,49 +46,49 @@ The subsystems interact as follows during the four operational modes:
 ### Capture Mode
 
 ```text
-CLI Subsystem → Configuration Subsystem → (shell)
+Cli Subsystem → Configuration Subsystem → (shell)
                                         ↓
                                Capture Subsystem (VersionInfo.SaveToFile)
 ```
 
-1. The CLI Subsystem (Program) parses arguments and calls `RunCapture`.
+1. The Cli Subsystem (Program) parses arguments and calls `RunCapture`.
 2. `RunCapture` uses the Configuration Subsystem to load `.versionmark.yaml` and call
    `FindVersions`, which executes shell commands and extracts version strings.
 3. The result is saved to disk by `VersionInfo.SaveToFile` (Capture Subsystem).
 
 ### Publish Mode
 
 ```text
-CLI Subsystem → Capture Subsystem (VersionInfo.LoadFromFile) → Publish Subsystem
+Cli Subsystem → Capture Subsystem (VersionInfo.LoadFromFile) → Publishing Subsystem
                                                                        ↓
                                                              markdown report file
 ```
 
-1. The CLI Subsystem (Program) parses arguments and calls `RunPublish`.
+1. The Cli Subsystem (Program) parses arguments and calls `RunPublish`.
 2. `RunPublish` resolves glob patterns, then uses the Capture Subsystem to load each
    JSON file via `VersionInfo.LoadFromFile`.
-3. The Publish Subsystem (`MarkdownFormatter.Format`) converts the loaded records into
+3. The Publishing Subsystem (`MarkdownFormatter.Format`) converts the loaded records into
    a markdown string, which is written to the report file.
 
 ### Lint Mode
 
 ```text
-CLI Subsystem → Lint Subsystem
+Cli Subsystem → Linting Subsystem
 ```
 
-1. The CLI Subsystem (Program) calls `RunLint`, which resolves the config file path.
-2. The Lint Subsystem validates the YAML structure and reports all issues.
+1. The Cli Subsystem (Program) calls `RunLint`, which resolves the config file path.
+2. The Linting Subsystem validates the YAML structure and reports all issues.
 
 ### Validate Mode
 
 ```text
-CLI Subsystem → Validation Subsystem
+Cli Subsystem → SelfTest Subsystem
                        ↓
              (exercises Capture, Publish, and Lint modes internally)
 ```
 
-1. The CLI Subsystem (Program) calls `Validation.Run`.
-2. The Validation Subsystem exercises capture, publish, and lint modes end-to-end,
+1. The Cli Subsystem (Program) calls `Validation.Run`.
+2. The SelfTest Subsystem exercises capture, publish, and lint modes end-to-end,
    using `PathHelpers` to safely construct paths inside a temporary directory.
 
 The self-validation suite includes the following named tests, which serve as evidence

requirements.yaml

@@ -7,19 +7,19 @@
 includes:
   - docs/reqstream/versionmark-system.yaml
   - docs/reqstream/platform-requirements.yaml
-  - docs/reqstream/subsystem-command-line.yaml
+  - docs/reqstream/subsystem-cli.yaml
   - docs/reqstream/unit-program.yaml
   - docs/reqstream/unit-context.yaml
   - docs/reqstream/subsystem-capture.yaml
   - docs/reqstream/unit-version-info.yaml
-  - docs/reqstream/subsystem-publish.yaml
+  - docs/reqstream/subsystem-publishing.yaml
   - docs/reqstream/unit-formatter.yaml
   - docs/reqstream/subsystem-configuration.yaml
   - docs/reqstream/unit-version-mark-config.yaml
   - docs/reqstream/unit-tool-config.yaml
-  - docs/reqstream/subsystem-lint.yaml
+  - docs/reqstream/subsystem-linting.yaml
   - docs/reqstream/unit-lint.yaml
-  - docs/reqstream/subsystem-validation.yaml
+  - docs/reqstream/subsystem-selftest.yaml
   - docs/reqstream/unit-validation.yaml
   - docs/reqstream/unit-path-helpers.yaml
   - docs/reqstream/ots-mstest.yaml

src/DemaConsulting.VersionMark/VersionInfo.cs → src/DemaConsulting.VersionMark/Capture/VersionInfo.cs

@@ -20,7 +20,7 @@
 
 using System.Text.Json;
 
-namespace DemaConsulting.VersionMark;
+namespace DemaConsulting.VersionMark.Capture;
 
 /// <summary>
 ///     Version information record containing Job ID and tool versions.

src/DemaConsulting.VersionMark/Context.cs → src/DemaConsulting.VersionMark/Cli/Context.cs

@@ -18,7 +18,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
-namespace DemaConsulting.VersionMark;
+namespace DemaConsulting.VersionMark.Cli;
 
 /// <summary>
 ///     Context class that handles command-line arguments and program output.

src/DemaConsulting.VersionMark/VersionMarkConfig.cs → src/DemaConsulting.VersionMark/Configuration/VersionMarkConfig.cs

@@ -21,9 +21,10 @@
 using System.Diagnostics;
 using System.Runtime.InteropServices;
 using System.Text.RegularExpressions;
+using DemaConsulting.VersionMark.Capture;
 using YamlDotNet.RepresentationModel;
 
-namespace DemaConsulting.VersionMark;
+namespace DemaConsulting.VersionMark.Configuration;
 
 /// <summary>
 ///     Configuration for a single tool in .versionmark.yaml file.

src/DemaConsulting.VersionMark/Lint.cs → src/DemaConsulting.VersionMark/Linting/Lint.cs

@@ -19,9 +19,10 @@
 // SOFTWARE.
 
 using System.Text.RegularExpressions;
+using DemaConsulting.VersionMark.Cli;
 using YamlDotNet.RepresentationModel;
 
-namespace DemaConsulting.VersionMark;
+namespace DemaConsulting.VersionMark.Linting;
 
 /// <summary>
 ///     Provides lint functionality for checking .versionmark.yaml configuration files.
@@ -177,7 +178,7 @@
     /// <param name="toolName">The name of the tool being validated.</param>
     /// <param name="toolNode">The YAML mapping node for the tool.</param>
     /// <returns>The number of issues found.</returns>
     private static int ValidateTool(Context context, string configFile, string toolName, YamlMappingNode toolNode)
     {
         var issueCount = 0;
         var hasCommand = false;

src/DemaConsulting.VersionMark/Program.cs

@@ -19,6 +19,12 @@
 // SOFTWARE.
 
 using System.Reflection;
+using DemaConsulting.VersionMark.Capture;
+using DemaConsulting.VersionMark.Cli;
+using DemaConsulting.VersionMark.Configuration;
+using DemaConsulting.VersionMark.Linting;
+using DemaConsulting.VersionMark.Publishing;
+using DemaConsulting.VersionMark.SelfTest;
 using Microsoft.Extensions.FileSystemGlobbing;
 using Microsoft.Extensions.FileSystemGlobbing.Abstractions;