demaconsulting · Malcolmnixon · Mar 31, 2026 · Mar 31, 2026 · Mar 31, 2026 · Mar 31, 2026
diff --git a/.reviewmark.yaml b/.reviewmark.yaml
@@ -0,0 +1,138 @@
+---
+# ReviewMark Configuration File
+needs-review:
+  - "**/*.cs"
+  - "requirements.yaml"
+  - "docs/reqstream/**/*.yaml"
+  - "docs/design/**/*.md"
+  - "!**/obj/**"
+  - "!**/bin/**"
+
+evidence-source:
+  type: url
+  location: https://raw.githubusercontent.com/demaconsulting/BuildMark/reviews/index.json
+
+reviews:
+  # Software unit reviews - one per unit
+  - id: BuildMark-Program
+    title: Review of BuildMark Program Unit
+    paths:
+      - "docs/reqstream/unit-program.yaml"
+      - "docs/design/program.md"
+      - "src/**/Program.cs"
+      - "test/**/ProgramTests.cs"
+
+  - id: BuildMark-Context
+    title: Review of BuildMark Context Unit
+    paths:
+      - "docs/reqstream/cli/unit-context.yaml"
+      - "docs/design/cli/context.md"
+      - "src/**/Cli/Context.cs"
+      - "test/**/Cli/ContextTests.cs"
+
+  - id: BuildMark-Validation
+    title: Review of BuildMark Validation Unit
+    paths:
+      - "docs/reqstream/self-test/unit-validation.yaml"
+      - "docs/design/self-test/validation.md"
+      - "src/**/SelfTest/Validation.cs"
+      - "test/**/SelfTest/ValidationTests.cs"
+
+  - id: BuildMark-PathHelpers
+    title: Review of BuildMark PathHelpers Unit
+    paths:
+      - "docs/reqstream/utilities/unit-path-helpers.yaml"
+      - "docs/design/utilities/path-helpers.md"
+      - "src/**/Utilities/PathHelpers.cs"
+      - "test/**/Utilities/PathHelpersTests.cs"
+
+  - id: BuildMark-GitHubRepoConnector
+    title: Review of BuildMark GitHubRepoConnector Unit
+    paths:
+      - "docs/reqstream/repo-connectors/unit-github-repo-connector.yaml"
+      - "docs/design/repo-connectors/github-repo-connector.md"
+      - "src/**/GitHub/GitHubRepoConnector.cs"
+      - "src/**/GitHub/GitHubGraphQLClient.cs"
+      - "src/**/GitHub/GitHubGraphQLTypes.cs"
+      - "test/**/RepoConnectors/GitHub/GitHubRepoConnectorTests.cs"
+      - "test/**/RepoConnectors/GitHub/GitHubGraphQLClientFindIssueIdsTests.cs"
+      - "test/**/RepoConnectors/GitHub/GitHubGraphQLClientGetAllIssuesTests.cs"
+      - "test/**/RepoConnectors/GitHub/GitHubGraphQLClientGetAllTagsTests.cs"
+      - "test/**/RepoConnectors/GitHub/GitHubGraphQLClientGetCommitsTests.cs"
+      - "test/**/RepoConnectors/GitHub/GitHubGraphQLClientGetPullRequestsTests.cs"
+      - "test/**/RepoConnectors/GitHub/GitHubGraphQLClientGetReleasesTests.cs"
+      - "test/**/RepoConnectors/GitHub/MockGitHubGraphQLHttpMessageHandler.cs"
+      - "test/**/RepoConnectors/GitHub/MockGitHubGraphQLHttpMessageHandlerTests.cs"
+      - "test/**/RepoConnectors/GitHub/MockableGitHubRepoConnector.cs"
+
+  # Subsystem reviews
+  - id: BuildMark-Cli
+    title: Review of BuildMark Cli subsystem (command-line interface)
+    paths:
+      - "docs/reqstream/cli/subsystem-cli.yaml"
+      - "docs/design/cli/cli.md"
+      - "docs/design/cli/context.md"
+      - "docs/design/program.md"
+
+  - id: BuildMark-SelfTest
+    title: Review of BuildMark SelfTest subsystem (self-validation)
+    paths:
+      - "docs/reqstream/self-test/subsystem-self-test.yaml"
+      - "docs/design/self-test/self-test.md"
+      - "docs/design/self-test/validation.md"
+
+  - id: BuildMark-Utilities
+    title: Review of BuildMark Utilities subsystem (shared utilities)
+    paths:
+      - "docs/reqstream/utilities/subsystem-utilities.yaml"
+      - "docs/design/utilities/utilities.md"
+      - "docs/design/utilities/path-helpers.md"
+
+  - id: BuildMark-RepoConnectors
+    title: Review of BuildMark RepoConnectors subsystem (repository connectors)
+    paths:
+      - "docs/reqstream/repo-connectors/subsystem-repo-connectors.yaml"   # subsystem requirements
+      - "docs/design/repo-connectors/repo-connectors.md"                  # subsystem design
+      - "docs/design/repo-connectors/github-repo-connector.md"            # GitHubRepoConnector unit design
+      - "src/**/RepoConnectors/IRepoConnector.cs"                         # connector interface
+      - "src/**/RepoConnectors/RepoConnectorBase.cs"                      # connector base class
+      - "src/**/RepoConnectors/RepoConnectorFactory.cs"                   # connector factory
+      - "src/**/RepoConnectors/MockRepoConnector.cs"                      # mock connector
+      - "src/**/RepoConnectors/ProcessRunner.cs"                          # process runner
+      - "test/**/RepoConnectors/MockRepoConnectorTests.cs"                # mock connector tests
+      - "test/**/RepoConnectors/ProcessRunnerTests.cs"                    # process runner tests
+      - "test/**/RepoConnectors/RepoConnectorFactoryTests.cs"             # factory tests
+
+  # System review
+  - id: BuildMark-System
+    title: Review of BuildMark system-level behavior and integration
+    paths:
+      - "docs/reqstream/buildmark-system.yaml"
+      - "docs/reqstream/platform-requirements.yaml"
+      - "docs/design/introduction.md"
+      - "test/**/IntegrationTests.cs"
+      - "test/**/Runner.cs"
+      - "test/**/AssemblyInfo.cs"
+
+  - id: BuildMark-Design
+    title: Review of BuildMark Software Design Document
+    paths:
+      - "docs/design/**/*.md"
+
+  # All-requirements review
+  - id: BuildMark-AllRequirements
+    title: Review of all BuildMark requirements files
+    paths:
+      - "requirements.yaml"
+      - "docs/reqstream/**/*.yaml"
+
+  # OTS dependency reviews
+  - id: OTS-Dependencies
+    title: Review of Off-The-Shelf Software Dependencies
+    paths:
+      - "docs/reqstream/ots-mstest.yaml"
+      - "docs/reqstream/ots-reqstream.yaml"
+      - "docs/reqstream/ots-buildmark.yaml"
+      - "docs/reqstream/ots-versionmark.yaml"
+      - "docs/reqstream/ots-sarifmark.yaml"
+      - "docs/reqstream/ots-sonarmark.yaml"
diff --git a/docs/design/cli/cli.md b/docs/design/cli/cli.md
@@ -0,0 +1,43 @@
+# Cli Subsystem
+
+## Overview
+
+The Cli subsystem provides the command-line interface layer for BuildMark. It
+parses arguments supplied by the user, routes output to the console or a log file,
+and exposes the parsed state to the rest of the system via the `Context` object.
+
+The subsystem has no dependencies on other BuildMark subsystems. All other
+subsystems receive a `Context` from the caller rather than creating one themselves.
+
+## Units
+
+| Unit      | File             | Responsibility                              |
+|-----------|------------------|---------------------------------------------|
+| `Context` | `Cli/Context.cs` | Argument parsing, output routing, exit code |
+
+## Interfaces
+
+`Context` exposes the following outward-facing interface consumed by `Program`:
+
+| Member                | Kind     | Description                                        |
+|-----------------------|----------|----------------------------------------------------|
+| `Create(args)`        | Method   | Factory: parse arguments and return a `Context`    |
+| `Version`             | Property | Set when `--version` / `-v` flag is present        |
+| `Help`                | Property | Set when `--help` / `-h` / `-?` flag is present    |
+| `Silent`              | Property | Set when `--silent` flag is present                |
+| `Validate`            | Property | Set when `--validate` flag is present              |
+| `BuildVersion`        | Property | Value of `--build-version` argument                |
+| `ReportFile`          | Property | Value of `--report` argument                       |
+| `ReportDepth`         | Property | Value of `--report-depth` argument (default: 1)    |
+| `IncludeKnownIssues`  | Property | Set when `--include-known-issues` flag is present  |
+| `ResultsFile`         | Property | Value of `--results` argument                      |
+| `ConnectorFactory`    | Property | Optional factory for dependency injection in tests |
+| `ExitCode`            | Property | Returns 0 unless `WriteError` has been called      |
+| `WriteLine(message)`  | Method   | Writes a line to console (if not silent) and log   |
+| `WriteError(message)` | Method   | Writes an error line and sets exit code to 1       |
+| `Dispose()`           | Method   | Closes the log file if one was opened              |
+
+## Interactions
+
+The Cli subsystem has no dependencies on other BuildMark subsystems. `Program`
+creates a `Context` and passes it to other subsystems as needed.
diff --git a/docs/design/cli/context.md b/docs/design/cli/context.md
@@ -0,0 +1,87 @@
+# Context
+
+## Overview
+
+`Context` is the sole unit in the Cli subsystem. It owns the lifecycle of
+command-line argument parsing, console and log-file output, and exit-code tracking.
+`Program` creates exactly one `Context` per invocation and passes it to all other
+units that need to write output or read configuration.
+
+`Context` implements `IDisposable`. Callers must dispose of the context after use
+so that any open log file is properly flushed and closed.
+
+## Data Model
+
+### Parsed Flags
+
+| Property             | Type   | Default | Source                   |
+|----------------------|--------|---------|--------------------------|
+| `Version`            | `bool` | `false` | `-v` / `--version`       |
+| `Help`               | `bool` | `false` | `-?` / `-h` / `--help`   |
+| `Silent`             | `bool` | `false` | `--silent`               |
+| `Validate`           | `bool` | `false` | `--validate`             |
+| `IncludeKnownIssues` | `bool` | `false` | `--include-known-issues` |
+
+### Parsed Arguments
+
+| Property           | Type                    | Default | Source                      |
+|--------------------|-------------------------|---------|-----------------------------|
+| `BuildVersion`     | `string?`               | `null`  | `--build-version <version>` |
+| `ReportFile`       | `string?`               | `null`  | `--report <file>`           |
+| `ReportDepth`      | `int`                   | `1`     | `--report-depth <depth>`    |
+| `ResultsFile`      | `string?`               | `null`  | `--results <file>`          |
+| `ConnectorFactory` | `Func<IRepoConnector>?` | `null`  | Injected via overload       |
+
+### Derived State
+
+| Property   | Type  | Description                                       |
+|------------|-------|---------------------------------------------------|
+| `ExitCode` | `int` | `0` if no errors have been written; `1` otherwise |
+
+## Methods
+
+### `Create(string[] args) → Context`
+
+Public factory method. Constructs a new `Context` by forwarding to
+`ArgumentParser`, then opens a log file if `--log` was specified.
+Throws `ArgumentException` for invalid arguments; throws
+`InvalidOperationException` if the log file cannot be opened.
+
+### `Create(string[] args, Func<IRepoConnector>? connectorFactory) → Context`
+
+Overload that additionally accepts a connector factory for dependency injection
+during testing. The factory is stored on `ConnectorFactory` and used by
+`Program.ProcessBuildNotes` instead of the default factory.
+
+### `OpenLogFile(string logFile)`
+
+Opens the specified file for writing in overwrite mode (truncating any existing
+file) with `AutoFlush` enabled. If the directory does not exist, the method
+throws `InvalidOperationException`.
+
+### `WriteLine(string message)`
+
+Writes `message` to standard output (unless `Silent` is set) and to the log file
+(if open).
+
+### `WriteError(string message)`
+
+Writes `message` to standard error in red (unless `Silent` is set) and to the
+log file (if open). Sets the internal error flag so that `ExitCode` returns `1`.
+
+### `Dispose()`
+
+Flushes and closes the log file stream. Safe to call multiple times.
+
+## Inner Class: `ArgumentParser`
+
+`ArgumentParser` is a private nested class used exclusively by `Create`. It
+iterates over the argument array and classifies each token:
+
+- Short flags (`-v`, `-h`, `-?`) and long flags (`--version`, `--help`, etc.)
+  are mapped to boolean properties.
+- Value arguments (`--build-version`, `--report`, `--report-depth`, `--results`,
+  `--log`) expect the next token as their value and throw `ArgumentException` if
+  no next token is present.
+- `--report-depth` additionally validates that the value is a positive integer.
+- Any unrecognized token causes `ArgumentException` to be thrown.
diff --git a/docs/design/definition.yaml b/docs/design/definition.yaml
@@ -0,0 +1,24 @@
+---
+resource-path:
+  - docs/design
+  - docs/design/cli
+  - docs/design/self-test
+  - docs/design/utilities
+  - docs/design/repo-connectors
+  - docs/template
+
+input-files:
+  - docs/design/title.txt
+  - docs/design/introduction.md
+  - docs/design/program.md
+  - docs/design/cli/cli.md
+  - docs/design/cli/context.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
+  - docs/design/repo-connectors/repo-connectors.md
+  - docs/design/repo-connectors/github-repo-connector.md
+template: template.html
+table-of-contents: true
+number-sections: true
diff --git a/docs/design/introduction.md b/docs/design/introduction.md
@@ -0,0 +1,99 @@
+# Introduction
+
+This document provides the detailed design for BuildMark, a .NET command-line tool
+that generates markdown build notes from GitHub repository metadata.
+
+## Purpose
+
+The purpose of this document is to describe the internal design of each software unit
+that comprises BuildMark. It captures data models, algorithms, key methods, and
+inter-unit interactions at a level of detail sufficient for formal code review,
+compliance verification, and future maintenance. The document does not restate
+requirements; it explains how they are realized.
+
+## Scope
+
+This document covers the detailed design of the following software units:
+
+- **Program** — entry point and execution orchestrator (`Program.cs`)
+- **Context** — command-line argument parser and I/O owner (`Cli/Context.cs`)
+- **Validation** — self-validation test runner (`SelfTest/Validation.cs`)
+- **PathHelpers** — safe path combination utilities (`Utilities/PathHelpers.cs`)
+- **GitHubRepoConnector** — GitHub GraphQL API integration (`RepoConnectors/GitHub/GitHubRepoConnector.cs`)
+
+The following topics are out of scope:
+
+- External library internals
+- Build pipeline configuration
+- Deployment and packaging
+
+## Software Structure
+
+The following tree shows how the BuildMark software items are organized across the
+system, subsystem, and unit levels:
+
+```text
+BuildMark (System)
+├── Program (Unit)
+├── Cli (Subsystem)
+│   └── Context (Unit)
+├── SelfTest (Subsystem)
+│   └── Validation (Unit)
+├── Utilities (Subsystem)
+│   └── PathHelpers (Unit)
+└── RepoConnectors (Subsystem)
+    └── GitHubRepoConnector (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.BuildMark/
+├── Program.cs                               — entry point and execution orchestrator
+├── BuildInformation.cs                      — build information data model
+├── ItemInfo.cs                              — item information data model
+├── Version.cs                               — version information
+├── VersionTag.cs                            — version tag representation
+├── WebLink.cs                               — web link helper
+├── Cli/
+│   └── Context.cs                           — command-line argument parser and I/O owner
+├── SelfTest/
+│   └── Validation.cs                        — self-validation test runner
+├── Utilities/
+│   └── PathHelpers.cs                       — safe path combination utilities
+└── RepoConnectors/
+    ├── IRepoConnector.cs                    — repository connector interface
+    ├── RepoConnectorBase.cs                 — repository connector base class
+    ├── RepoConnectorFactory.cs              — repository connector factory
+    ├── MockRepoConnector.cs                 — mock repository connector for testing
+    ├── ProcessRunner.cs                     — process runner for Git commands
+    └── GitHub/
+        ├── GitHubRepoConnector.cs           — GitHub API integration
+        ├── GitHubGraphQLClient.cs           — GraphQL API client
+        └── GitHubGraphQLTypes.cs            — GraphQL type definitions
+```
+
+The test project mirrors the same layout under `test/DemaConsulting.BuildMark.Tests/`.
+
+## Document Conventions
+
+Throughout this document:
+
+- Class names, method names, property names, and file names appear in `monospace` font.
+- The word **shall** denotes a design constraint that the implementation must satisfy.
+- Section headings within each unit chapter follow a consistent structure: overview, data model,
+  methods/algorithms, and interactions with other units.
+- Text tables are used in preference to diagrams, which may not render in all PDF viewers.
+
+## References
+
+- [BuildMark User Guide][user-guide]
+- [BuildMark Repository][repo]
+
+[user-guide]: ../guide/guide.md
+[repo]: https://github.com/demaconsulting/BuildMark