diff --git a/.reviewmark.yaml b/.reviewmark.yaml new file mode 100644 index 0000000..f9af4e7 --- /dev/null +++ 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 new file mode 100644 index 0000000..753f6a6 --- /dev/null +++ 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 new file mode 100644 index 0000000..b725ccb --- /dev/null +++ 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 ` | +| `ReportFile` | `string?` | `null` | `--report ` | +| `ReportDepth` | `int` | `1` | `--report-depth ` | +| `ResultsFile` | `string?` | `null` | `--results ` | +| `ConnectorFactory` | `Func?` | `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? 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 new file mode 100644 index 0000000..9af1110 --- /dev/null +++ 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 new file mode 100644 index 0000000..87ff5f5 --- /dev/null +++ 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 diff --git a/docs/design/program.md b/docs/design/program.md new file mode 100644 index 0000000..f28e869 --- /dev/null +++ b/docs/design/program.md @@ -0,0 +1,61 @@ +# Program + +## Overview + +`Program` is the top-level unit of BuildMark. It owns the application entry point, +creates the `Context` object from command-line arguments, and dispatches execution +to the appropriate handler based on the parsed flags. + +The unit contains two public methods: `Main`, which is called by the .NET runtime, +and `Run`, which accepts an existing `Context` and performs the main execution logic. +`Run` is exposed separately so that integration tests can inject a pre-configured +`Context` without repeating argument parsing. + +## Data Model + +`Program` exposes a single static property: + +| Property | Type | Description | +|-----------|----------|------------------------------------------------| +| `Version` | `string` | The tool version read from assembly attributes | + +The version is resolved at startup by inspecting `AssemblyInformationalVersionAttribute` +first, then falling back to `AssemblyVersionAttribute`, and finally defaulting to +`"0.0.0"` if neither attribute is present. + +## Methods + +### `Main(string[] args) → int` + +The application entry point. It creates a `Context` from the supplied command-line +arguments and delegates to `Run`. Any `ArgumentException` or +`InvalidOperationException` is caught, written to the error output via +`Context.WriteError`, and results in an exit code of 1. Any other exception is +re-thrown after logging so the runtime can report an unhandled exception. + +### `Run(Context context) → int` + +Executes the main program logic against an already-constructed `Context`. The +method applies the following priority order: + +1. If `context.Version` is set, print the version string and return 0. +2. If `context.Help` is set, print the usage message and return 0. +3. If `context.Validate` is set, delegate to `Validation.Run(context)` and return + the context exit code. +4. Otherwise, call `ProcessBuildNotes(context)` to generate the build report. + +### `ProcessBuildNotes(Context context)` + +Resolves the build version, creates a repository connector via +`context.ConnectorFactory` (or the default `RepoConnectorFactory`), fetches +`BuildInformation`, writes a summary to the console, and optionally writes the +markdown report to `context.ReportFile`. + +## Interactions + +| Unit / Subsystem | Role | +|------------------------|-------------------------------------------------------------------| +| `Context` | Provides parsed flags, arguments, and output methods | +| `Validation` | Executes self-validation when `--validate` flag is set | +| `RepoConnectorFactory` | Creates the default `IRepoConnector` implementation | +| `BuildInformation` | Returned by the connector; converted to markdown via `ToMarkdown` | diff --git a/docs/design/repo-connectors/github-repo-connector.md b/docs/design/repo-connectors/github-repo-connector.md new file mode 100644 index 0000000..28828e6 --- /dev/null +++ b/docs/design/repo-connectors/github-repo-connector.md @@ -0,0 +1,63 @@ +# GitHubRepoConnector + +## Overview + +`GitHubRepoConnector` is the production unit in the RepoConnectors subsystem. It +implements `RepoConnectorBase` and uses `GitHubGraphQLClient` to query the GitHub +GraphQL API for issues, pull requests, version tags, and commits. + +The unit reads the repository URL and current commit hash from Git, resolves the +GitHub token from environment variables, and fetches all data needed to construct +a `BuildInformation` record. + +## Data Model + +### Authentication + +The connector resolves the GitHub token using the following priority order: + +1. `GH_TOKEN` environment variable +2. `GITHUB_TOKEN` environment variable +3. Output of `gh auth token` command + +If no token is found, the connector throws `InvalidOperationException`. + +### Label Mapping + +GitHub issue and pull request labels are mapped to normalized types: + +| GitHub Labels | Normalized Type | +|--------------------------------------------|-----------------| +| `bug`, `defect` | `"bug"` | +| `feature`, `enhancement` | `"feature"` | +| `documentation`, `performance`, `security` | label name | + +Items labelled as `"bug"` are placed in the `Bugs` list; all others go to `Changes`. + +## Methods + +### `GetBuildInformationAsync(Version? version) → BuildInformation` + +Main entry point. Performs the following steps: + +1. Get repository metadata (URL, branch, current commit hash) from Git. +2. Parse the owner and repository name from the Git remote URL. +3. Resolve the GitHub authentication token. +4. Create a `GitHubGraphQLClient` with the resolved token. +5. Fetch all tags, commits, releases, issues, and pull requests via GraphQL. +6. Determine the target version tag (highest tag matching `version`, or latest). +7. Determine the baseline version tag (highest tag below the target). +8. Get all commits between the baseline and target. +9. Collect changes and bugs from pull requests merged in the commit range. +10. Collect known issues (open issues not included in this build). +11. Sort all lists chronologically. +12. Generate the full changelog URL from the baseline and target tags. +13. Return the assembled `BuildInformation` record. + +## Interactions + +| Unit / Subsystem | Role | +|-----------------------|-------------------------------------------------| +| `GitHubGraphQLClient` | Executes GraphQL queries against the GitHub API | +| `ProcessRunner` | Runs Git commands to get repository metadata | +| `BuildInformation` | The output record assembled from fetched data | diff --git a/docs/design/repo-connectors/repo-connectors.md b/docs/design/repo-connectors/repo-connectors.md new file mode 100644 index 0000000..b18923d --- /dev/null +++ b/docs/design/repo-connectors/repo-connectors.md @@ -0,0 +1,38 @@ +# RepoConnectors Subsystem + +## Overview + +The RepoConnectors subsystem abstracts access to repository metadata for BuildMark. +It provides an interface and base class for repository connectors, a factory for +creating the appropriate connector, a mock connector for testing, and a process +runner for executing Git commands. + +The primary production connector is `GitHubRepoConnector`, which queries the GitHub +GraphQL API to retrieve issues, pull requests, tags, and commits. + +## Units + +| Unit | File | Responsibility | +|------------------------|------------------------------------------------|-----------------------------------------| +| `IRepoConnector` | `RepoConnectors/IRepoConnector.cs` | Interface for all repository connectors | +| `RepoConnectorBase` | `RepoConnectors/RepoConnectorBase.cs` | Base class with common connector logic | +| `RepoConnectorFactory` | `RepoConnectors/RepoConnectorFactory.cs` | Creates the appropriate connector | +| `MockRepoConnector` | `RepoConnectors/MockRepoConnector.cs` | In-memory connector for testing | +| `ProcessRunner` | `RepoConnectors/ProcessRunner.cs` | Runs Git commands via the shell | +| `GitHubRepoConnector` | `RepoConnectors/GitHub/GitHubRepoConnector.cs` | GitHub GraphQL API connector | + +## Interfaces + +`IRepoConnector` defines the contract for all connectors: + +| Member | Kind | Description | +|-------------------------------------|--------|----------------------------------| +| `GetBuildInformationAsync(version)` | Method | Fetch complete build information | + +## Interactions + +| Unit / Subsystem | Role | +|--------------------|-------------------------------------------------------------| +| `Program` | Creates a connector via `RepoConnectorFactory` and calls it | +| `Validation` | Uses `MockRepoConnector` directly for self-tests | +| `BuildInformation` | The data record returned by connectors | diff --git a/docs/design/self-test/self-test.md b/docs/design/self-test/self-test.md new file mode 100644 index 0000000..9807beb --- /dev/null +++ b/docs/design/self-test/self-test.md @@ -0,0 +1,32 @@ +# SelfTest Subsystem + +## Overview + +The SelfTest subsystem provides a self-validation capability for BuildMark. When the +user passes `--validate`, the subsystem exercises the core functionality of the tool +in the current environment, using a `MockRepoConnector` to avoid external API calls. + +The subsystem has no dependencies on the Cli subsystem beyond receiving a `Context` +as its input parameter. + +## Units + +| Unit | File | Responsibility | +|--------------|--------------------------|----------------------------------------------| +| `Validation` | `SelfTest/Validation.cs` | Runs self-tests and writes results to a file | + +## Interfaces + +`Validation` exposes one public method: + +| Member | Kind | Description | +|----------------|--------|------------------------------------------------------------| +| `Run(context)` | Method | Execute all self-tests and optionally write a results file | + +## Interactions + +| Unit / Subsystem | Role | +|---------------------|-------------------------------------------------------| +| `Context` | Provides output methods and `ResultsFile` path | +| `MockRepoConnector` | Provides deterministic repository data for self-tests | +| `BuildInformation` | Generated during tests to verify report content | diff --git a/docs/design/self-test/validation.md b/docs/design/self-test/validation.md new file mode 100644 index 0000000..9f207dd --- /dev/null +++ b/docs/design/self-test/validation.md @@ -0,0 +1,66 @@ +# Validation + +## Overview + +`Validation` is the sole unit in the SelfTest subsystem. It runs a fixed set of +self-tests that exercise the core functionality of BuildMark without requiring +network access or external tools beyond Git. Results are written to the console and, +optionally, to a TRX or JUnit XML results file. + +The unit is invoked by `Program.Run` when the `--validate` flag is set. + +## Data Model + +`Validation` has no persistent state. All data is local to the `Run` method and +its helpers. Test results are accumulated in a list of `TestResult` records that +are written to a file at the end of the run. + +### `TemporaryDirectory` Helper + +A private nested class that creates a temporary directory on construction and +deletes it (with all contents) on disposal. Used to isolate test artifacts. + +## Methods + +### `Run(Context context)` + +Entry point for self-validation. It: + +1. Prints a header showing the OS, .NET runtime, and current timestamp. +2. Executes each self-test method in sequence. +3. Prints a summary of passed and failed tests. +4. If `context.ResultsFile` is set, writes the results in TRX or JUnit XML format + (determined by the file extension `.trx` or `.xml`). +5. Writes any unsupported extension as an error. +6. Sets `context.ExitCode` to `1` if any test fails. + +### `RunMarkdownReportGeneration` + +Creates a `MockRepoConnector` with representative data, generates a +`BuildInformation` record, calls `ToMarkdown`, writes the output to a temporary +file, and verifies the file contains expected version and content markers. + +### `RunGitIntegration` + +Runs the tool against the local Git repository to verify that version, commit +hash, and previous version can be extracted correctly. Validates the output +against expected patterns. + +### `RunIssueTracking` + +Uses `MockRepoConnector` to verify that issues and pull requests are categorized +and collected correctly into the `Changes` and `Bugs` lists of `BuildInformation`. + +### `RunKnownIssuesReporting` + +Uses `MockRepoConnector` to verify that known issues are included in the markdown +report when the `--include-known-issues` flag is set. + +## Interactions + +| Unit / Subsystem | Role | +|---------------------|--------------------------------------------------------------------------------------| +| `Context` | Provides output methods, `ResultsFile`, and exit code sink | +| `MockRepoConnector` | Supplies deterministic data for all tests | +| `BuildInformation` | Target of the tests; validated against expected content | +| `PathHelpers` | Used directly (e.g., `SafePathCombine`) to build temp, log, and report file paths | diff --git a/docs/design/title.txt b/docs/design/title.txt new file mode 100644 index 0000000..d9ce920 --- /dev/null +++ b/docs/design/title.txt @@ -0,0 +1,13 @@ +--- +title: BuildMark Software Design Document +subtitle: A .NET CLI Tool for Generating Build Notes from GitHub +author: DEMA Consulting +description: Detailed design document for the BuildMark tool +lang: en-US +keywords: + - BuildMark + - .NET + - Command-Line Tool + - Design + - Software Design Document +--- diff --git a/docs/design/utilities/path-helpers.md b/docs/design/utilities/path-helpers.md new file mode 100644 index 0000000..ea16d89 --- /dev/null +++ b/docs/design/utilities/path-helpers.md @@ -0,0 +1,46 @@ +# PathHelpers + +## Overview + +`PathHelpers` is the sole unit in the Utilities subsystem. It provides a single +static method, `SafePathCombine`, that combines a base path with a relative path +while defending against directory traversal attacks. + +The class is designed for use in contexts where user-supplied paths must be +restricted to a known base directory. + +## Data Model + +`PathHelpers` has no instance state. All functionality is exposed through a single +static method. + +## Methods + +### `SafePathCombine(string basePath, string relativePath) → string` + +Combines `basePath` and `relativePath` using `Path.Combine`, validating +that the result remains within `basePath`. + +**Preconditions (each violation throws an exception):** + +| Check | Exception | Message | +|------------------------------|-------------------------|------------------------------------------| +| `basePath` is null | `ArgumentNullException` | `paramName: "basePath"` | +| `relativePath` is null | `ArgumentNullException` | `paramName: "relativePath"` | +| `relativePath` contains `..` | `ArgumentException` | Invalid path component: `{relativePath}` | +| `relativePath` is rooted | `ArgumentException` | Invalid path component: `{relativePath}` | +| Result is outside `basePath` | `ArgumentException` | Invalid path component: `{relativePath}` | + +**Algorithm:** + +1. Validate `basePath` and `relativePath` for null. +2. Reject `relativePath` values containing `..` (fast-path traversal block). +3. Reject `relativePath` values where `Path.IsPathRooted` returns `true`. +4. Combine the paths using `Path.Combine(basePath, relativePath)`. +5. Compute `Path.GetRelativePath(Path.GetFullPath(basePath), Path.GetFullPath(combinedPath))`. +6. If the relative result starts with `..`, throw `ArgumentException`. +7. Return the combined path (result of `Path.Combine`). + +## Interactions + +`PathHelpers` has no dependencies on other BuildMark units or subsystems. diff --git a/docs/design/utilities/utilities.md b/docs/design/utilities/utilities.md new file mode 100644 index 0000000..7a77f82 --- /dev/null +++ b/docs/design/utilities/utilities.md @@ -0,0 +1,28 @@ +# Utilities Subsystem + +## Overview + +The Utilities subsystem provides shared helper classes used across the BuildMark +system. Currently it contains a single unit, `PathHelpers`, which provides safe +path combination with traversal prevention. + +The subsystem has no dependencies on other BuildMark subsystems. + +## Units + +| Unit | File | Responsibility | +|---------------|----------------------------|---------------------------------------------| +| `PathHelpers` | `Utilities/PathHelpers.cs` | Safe path combination with traversal checks | + +## Interfaces + +`PathHelpers` exposes the following static method: + +| Member | Kind | Description | +|-----------------------------------|--------|-------------------------------------------------| +| `SafePathCombine(base, relative)` | Method | Safely combine a base path with a relative path | + +## Interactions + +`PathHelpers` has no dependencies on other BuildMark subsystems. It is used by +any unit that needs to combine file paths safely. diff --git a/docs/reqstream/buildmark-system.yaml b/docs/reqstream/buildmark-system.yaml new file mode 100644 index 0000000..f8c7abe --- /dev/null +++ b/docs/reqstream/buildmark-system.yaml @@ -0,0 +1,312 @@ +--- +sections: + - title: BuildMark System Requirements + sections: + - title: Command-Line Interface + requirements: + - id: BuildMark-Cmd-Cli + title: The tool shall provide a command-line interface. + justification: | + A command-line interface is essential for BuildMark to integrate seamlessly into + automated build pipelines, CI/CD workflows, and scripting environments. This enables + developers and build systems to invoke the tool programmatically without requiring + a graphical user interface. + tests: + - IntegrationTest_VersionFlag_OutputsVersion + - IntegrationTest_HelpFlag_OutputsUsageInformation + children: + - BuildMark-Cli-Context + - BuildMark-Cli-Version + - BuildMark-Cli-Help + - BuildMark-Cli-Silent + - BuildMark-Cli-BuildVersion + - BuildMark-Cli-Report + - BuildMark-Cli-Log + - BuildMark-Cli-Validate + - BuildMark-Cli-Results + - BuildMark-Cli-ErrorOutput + - BuildMark-Cli-InvalidArgs + - BuildMark-Cli-ExitCode + + - id: BuildMark-Cmd-Version + title: The tool shall display version information when requested. + justification: | + Version information helps users identify which version of BuildMark they are running, + which is critical for debugging issues, ensuring compatibility, and tracking tool + updates across different environments. + tests: + - IntegrationTest_VersionFlag_OutputsVersion + children: + - BuildMark-Cli-Version + + - id: BuildMark-Cmd-Help + title: The tool shall display help information when requested. + justification: | + Help information provides users with immediate access to usage instructions, available + commands, and parameter descriptions. This improves user experience and reduces the + learning curve for new users without requiring external documentation. + tests: + - IntegrationTest_HelpFlag_OutputsUsageInformation + children: + - BuildMark-Cli-Help + + - id: BuildMark-Cmd-Silent + title: The tool shall support silent mode to suppress console output. + justification: | + Silent mode is essential for automated build environments where excessive console + output can clutter logs or interfere with parsing build results. This allows users + to control verbosity based on their specific use case. + tests: + - IntegrationTest_SilentFlag_SuppressesOutput + children: + - BuildMark-Cli-Silent + + - id: BuildMark-Cmd-Log + title: The tool shall support writing output to a log file. + justification: | + Log file support enables persistent storage of BuildMark output for audit trails, + troubleshooting, and post-build analysis. This is particularly valuable in automated + environments where console output may not be easily accessible. + tests: + - IntegrationTest_LogParameter_IsAccepted + children: + - BuildMark-Cli-Log + + - id: BuildMark-Cmd-BuildVersion + title: The tool shall support specifying a build version. + justification: | + Specifying a build version allows users to override or supplement version information + from source control, enabling flexible version management strategies and supporting + scenarios where version numbers are determined externally. + tests: + - IntegrationTest_BuildVersionParameter_IsAccepted + children: + - BuildMark-Cli-BuildVersion + + - id: BuildMark-Cmd-InvalidArgs + title: The tool shall validate command-line arguments. + justification: | + Argument validation prevents misuse of the tool and provides clear error messages + when invalid inputs are provided. This improves reliability, helps users identify + configuration errors early, and prevents unexpected behavior in automated workflows. + tests: + - IntegrationTest_InvalidArgument_ShowsError + children: + - BuildMark-Cli-InvalidArgs + + - id: BuildMark-Cmd-FilePaths + title: The tool shall handle invalid file paths gracefully. + justification: | + Graceful handling of invalid file paths prevents cryptic error messages and ensures + the tool fails safely when given incorrect paths. This improves user experience and + makes troubleshooting easier in production environments. + tests: + - IntegrationTest_InvalidArgument_ShowsError + children: + - BuildMark-Cli-InvalidArgs + + - id: BuildMark-Cmd-ExitCode + title: The tool shall return appropriate exit codes. + justification: | + Standard exit codes enable build automation systems and scripts to detect success + or failure conditions programmatically. This is fundamental for proper integration + into CI/CD pipelines and automated workflows. + tests: + - IntegrationTest_InvalidArgument_ShowsError + children: + - BuildMark-Cli-ExitCode + + - title: GitHub Integration + requirements: + - id: BuildMark-GH-BuildNotes + title: The tool shall generate build notes from GitHub repositories. + justification: | + Generating build notes from GitHub repositories automates the documentation of + changes between releases. This saves significant time during release processes and + ensures consistency in release documentation by deriving information directly from + source control history. + tests: + - BuildMark_GitIntegration + - BuildMark_MarkdownReportGeneration + children: + - BuildMark-RepoConnectors-GitHubConnector + + - id: BuildMark-GH-IssueTracking + title: The tool shall track issues and pull requests from GitHub. + justification: | + Tracking issues and pull requests provides traceability between code changes and + work items, enabling comprehensive release notes that link features, bug fixes, and + improvements to their corresponding GitHub issues and pull requests. + tests: + - BuildMark_IssueTracking + children: + - BuildMark-RepoConnectors-GitHubConnector + + - id: BuildMark-GH-VersionTags + title: The tool shall identify changes between version tags. + justification: | + Identifying changes between version tags enables differential release notes that + accurately capture what changed in each version. This is essential for semantic + versioning workflows and helps users understand the scope of changes between releases. + tests: + - BuildMark_GitIntegration + children: + - BuildMark-RepoConnectors-GitHubConnector + + - title: Report Generation + requirements: + - id: BuildMark-Rpt-Markdown + title: The tool shall generate markdown reports. + justification: | + Markdown is a widely-adopted, human-readable format that works seamlessly with + GitHub, documentation systems, and static site generators. Generating reports in + markdown format ensures broad compatibility and easy integration into existing + documentation workflows. + tests: + - BuildMark_MarkdownReportGeneration + - IntegrationTest_ReportParameter_IsAccepted + children: + - BuildMark-Program-Report + + - id: BuildMark-Rpt-Depth + title: The tool shall support configurable report depth. + justification: | + Configurable report depth allows BuildMark output to be embedded within existing + documentation structures by adjusting heading levels. This flexibility ensures + reports integrate properly regardless of the document hierarchy. + tests: + - IntegrationTest_ReportDepthParameter_IsAccepted + - BuildInformation_ToMarkdown_RespectsCustomHeadingDepth + children: + - BuildMark-Program-Report + + - id: BuildMark-Rpt-VersionInfo + title: The tool shall report version information in build notes. + justification: | + Version information clearly identifies which release the build notes describe, + providing essential context for users reviewing changes and enabling proper + organization of release documentation. + tests: + - BuildMark_MarkdownReportGeneration + children: + - BuildMark-Program-Report + + - id: BuildMark-Rpt-Changes + title: The tool shall report changes in build notes. + justification: | + Reporting changes documents new features and enhancements introduced in each + release, helping users understand the evolution of the software and make informed + decisions about upgrading. + tests: + - BuildMark_MarkdownReportGeneration + - BuildInformation_ToMarkdown_DisplaysNAForEmptyChanges + children: + - BuildMark-Program-Report + + - id: BuildMark-Rpt-BugFixes + title: The tool shall report bug fixes in build notes. + justification: | + Documenting bug fixes informs users about resolved issues, demonstrates ongoing + maintenance, and helps users determine if specific problems they encountered have + been addressed in newer versions. + tests: + - BuildMark_MarkdownReportGeneration + - BuildInformation_ToMarkdown_DisplaysNAForEmptyBugs + children: + - BuildMark-Program-Report + + - id: BuildMark-Rpt-KnownIssues + title: The tool shall support including known issues in build notes. + justification: | + Disclosing known issues in release notes promotes transparency, helps users avoid + known pitfalls, and manages expectations about current limitations. This improves + user trust and reduces support burden. + tests: + - BuildMark_KnownIssuesReporting + children: + - BuildMark-Program-Report + + - id: BuildMark-Rpt-VersionRange + title: The tool shall support filtering build notes by version range. + justification: | + Version range filtering enables generation of cumulative release notes covering + multiple versions or focused notes for specific releases. This flexibility supports + various documentation scenarios and user needs. + tests: + - BuildMark_MarkdownReportGeneration + children: + - BuildMark-Program-Report + + - id: BuildMark-Rpt-Hyperlinks + title: The tool shall include hyperlinks to issues and pull requests. + justification: | + Hyperlinks provide direct navigation to detailed information about changes, + enabling users to investigate specific items of interest and maintaining + traceability between release notes and source repository work items. + tests: + - BuildMark_MarkdownReportGeneration + - BuildInformation_ToMarkdown_IncludesIssueLinks + - BuildInformation_ToMarkdown_IncludesFullChangelogWhenLinkPresent + children: + - BuildMark-RepoConnectors-GitHubConnector + + - id: BuildMark-Rpt-Structure + title: The tool shall format build notes with proper markdown structure. + justification: | + Proper markdown structure ensures reports render correctly across different + markdown processors and documentation platforms. Well-structured documents are + more readable, professional, and maintainable. + tests: + - BuildMark_MarkdownReportGeneration + - BuildInformation_ToMarkdown_RespectsCustomHeadingDepth + - BuildInformation_ToMarkdown_UsesBulletLists + - BuildInformation_ToMarkdown_HandlesFirstReleaseWithNA + - BuildInformation_ToMarkdown_ExcludesFullChangelogWhenNoBaseline + children: + - BuildMark-Program-Report + + - title: Validation and Testing + requirements: + - id: BuildMark-Val-SelfValidation + title: The tool shall support self-validation mode. + justification: | + Self-validation mode allows users to validate the tool's functionality in their + environment, providing evidence that the user's environment does not introduce + unexpected behaviors, and giving users evidence they can rely on the tool's output. + tests: + - IntegrationTest_ValidateFlag_RunsSelfValidation + children: + - BuildMark-SelfTest-Qualification + + - id: BuildMark-Val-ResultsFiles + title: The tool shall write validation results to test result files. + justification: | + Writing validation results to files enables integration with testing frameworks, + CI/CD pipelines, and reporting tools. This allows BuildMark's validation results + to be tracked, analyzed, and reported alongside other test metrics. + tests: + - IntegrationTest_ResultsParameter_IsAccepted + children: + - BuildMark-SelfTest-ResultsOutput + + - id: BuildMark-Val-TrxFormat + title: The tool shall support TRX format for test results. + justification: | + TRX format support enables integration with Microsoft test tooling and Visual + Studio Test Explorer, providing native support for .NET development environments + and Azure DevOps pipelines. + tests: + - IntegrationTest_ResultsParameter_IsAccepted + children: + - BuildMark-SelfTest-ResultsOutput + + - id: BuildMark-Val-JUnitFormat + title: The tool shall support JUnit format for test results. + justification: | + JUnit format is a widely-supported standard across many CI/CD platforms and + testing tools. Supporting this format ensures BuildMark can integrate with diverse + toolchains beyond the Microsoft ecosystem. + tests: + - IntegrationTest_ResultsParameter_IsAccepted + children: + - BuildMark-SelfTest-ResultsOutput diff --git a/docs/reqstream/cli/subsystem-cli.yaml b/docs/reqstream/cli/subsystem-cli.yaml new file mode 100644 index 0000000..71d1422 --- /dev/null +++ b/docs/reqstream/cli/subsystem-cli.yaml @@ -0,0 +1,177 @@ +--- +# Cli Subsystem Requirements +# +# PURPOSE: +# - Define requirements for the BuildMark Cli subsystem +# - The Cli subsystem spans Context.cs (command-line argument parsing and I/O) +# - Subsystem requirements describe the externally visible command-line interface behavior + +sections: + - title: Cli Subsystem Requirements + requirements: + - id: BuildMark-Cli-Context + title: The Cli subsystem shall implement a Context class for command-line argument handling. + justification: | + Provides a standardized approach to command-line argument parsing and output + handling across all DEMA Consulting DotNet Tools. The Context class encapsulates + all parsed flags and output channels so that the rest of the tool has a single, + consistent entry point for CLI interaction. + tests: + - Context_Create_EmptyArguments_CreatesValidContext + - Context_Create_LongVersionFlag_SetsVersionProperty + - Context_Create_SilentFlag_SetsSilentProperty + - Context_Create_LogArgument_CreatesLogFile + - Context_Create_UnsupportedArgument_ThrowsArgumentException + children: + - BuildMark-Context-ArgumentParsing + - BuildMark-Context-InvalidArgs + - BuildMark-Context-Output + - BuildMark-Context-Silent + - BuildMark-Context-ErrorOutput + - BuildMark-Context-ExitCode + + - id: BuildMark-Cli-Version + title: The Cli subsystem shall support -v and --version flags to signal version display. + justification: | + Users need to quickly identify the version of the tool they are using for + troubleshooting and compatibility verification. + tests: + - Context_Create_LongVersionFlag_SetsVersionProperty + - Context_Create_ShortVersionFlag_SetsVersionProperty + - Program_Run_VersionFlag_OutputsVersionToConsole + - Program_Version_ReturnsValidVersion + - IntegrationTest_VersionFlag_OutputsVersion + children: + - BuildMark-Context-ArgumentParsing + + - id: BuildMark-Cli-Help + title: The Cli subsystem shall support -?, -h, and --help flags to signal help display. + justification: | + Users need access to command-line usage documentation without requiring + external resources. + tests: + - Context_Create_LongHelpFlag_SetsHelpProperty + - Context_Create_ShortHelpFlag_SetsHelpProperty + - Context_Create_QuestionMarkHelpFlag_SetsHelpProperty + - Program_Run_HelpFlag_OutputsHelpMessage + - IntegrationTest_HelpFlag_OutputsUsageInformation + children: + - BuildMark-Context-ArgumentParsing + + - id: BuildMark-Cli-Silent + title: The Cli subsystem shall support --silent flag to suppress console output. + justification: | + Enables automated scripts and CI/CD pipelines to run the tool without + cluttering output logs when only the exit code is needed. + tests: + - Context_Create_SilentFlag_SetsSilentProperty + - Context_WriteLine_Silent_DoesNotWriteToConsole + - IntegrationTest_SilentFlag_SuppressesOutput + children: + - BuildMark-Context-Silent + + - id: BuildMark-Cli-BuildVersion + title: The Cli subsystem shall support --build-version flag to specify the build version. + justification: | + Allows users to override or supplement version information from source control, + enabling flexible version management strategies and supporting scenarios where + version numbers are determined externally. + tests: + - Context_Create_BuildVersionArgument_SetsBuildVersionProperty + - IntegrationTest_BuildVersionParameter_IsAccepted + children: + - BuildMark-Context-ArgumentParsing + + - id: BuildMark-Cli-Report + title: The Cli subsystem shall support --report and --report-depth flags to configure report output. + justification: | + Enables users to direct build notes output to a specific file and embed it at + any heading level within a larger markdown document. + tests: + - Context_Create_ReportArgument_SetsReportFileProperty + - Context_Create_ReportDepthArgument_SetsReportDepthProperty + - IntegrationTest_ReportParameter_IsAccepted + - IntegrationTest_ReportDepthParameter_IsAccepted + children: + - BuildMark-Context-ArgumentParsing + + - id: BuildMark-Cli-Log + title: The Cli subsystem shall support --log flag to write output to a log file. + justification: | + Provides persistent logging for debugging and audit trails. Log files enable + post-run inspection of tool output without requiring console capture. + tests: + - Context_Create_LogArgument_CreatesLogFile + - Context_Create_LogWithoutValue_ThrowsArgumentException + - Context_WriteError_WithLogFile_WritesToLogFile + - Context_WriteLine_WithLogFile_WritesToLogFile + - IntegrationTest_LogParameter_IsAccepted + children: + - BuildMark-Context-Output + + - id: BuildMark-Cli-Validate + title: The Cli subsystem shall support --validate flag to signal self-validation. + justification: | + Provides a built-in mechanism to verify the tool is functioning correctly + in the deployment environment. + tests: + - Context_Create_ValidateFlag_SetsValidateProperty + - Program_Run_ValidateFlag_OutputsValidationMessage + - IntegrationTest_ValidateFlag_RunsSelfValidation + children: + - BuildMark-Context-ArgumentParsing + + - id: BuildMark-Cli-Results + title: The Cli subsystem shall support --results flag to specify a test results output file. + justification: | + Enables integration with CI/CD systems that expect standard test result formats + (TRX or JUnit XML). + tests: + - Context_Create_ResultsArgument_SetsResultsFileProperty + - Context_Create_ResultsWithoutValue_ThrowsArgumentException + - IntegrationTest_ResultsParameter_IsAccepted + children: + - BuildMark-Context-ArgumentParsing + + - id: BuildMark-Cli-ErrorOutput + title: The Cli subsystem shall write error messages to stderr. + justification: | + Error messages must be written to stderr so they remain visible to the user + without polluting stdout, which consumers may pipe or redirect for data capture. + tests: + - Context_WriteError_NotSilent_WritesToConsole + - IntegrationTest_InvalidArgument_ShowsError + children: + - BuildMark-Context-ErrorOutput + + - id: BuildMark-Cli-InvalidArgs + title: The Cli subsystem shall reject unknown or malformed command-line arguments with a descriptive error. + justification: | + Providing clear feedback for invalid arguments helps users quickly correct + mistakes and prevents silent misconfiguration in automated workflows. + tests: + - Context_Create_UnsupportedArgument_ThrowsArgumentException + - Context_Create_BuildVersionWithoutValue_ThrowsArgumentException + - Context_Create_ReportWithoutValue_ThrowsArgumentException + - Context_Create_ReportDepthWithoutValue_ThrowsArgumentException + - Context_Create_ReportDepthWithNonIntegerValue_ThrowsArgumentException + - Context_Create_ReportDepthWithZeroValue_ThrowsArgumentException + - Context_Create_ReportDepthWithNegativeValue_ThrowsArgumentException + - Context_Create_ResultsWithoutValue_ThrowsArgumentException + - Context_Create_LogWithoutValue_ThrowsArgumentException + - Context_Create_InvalidLogFilePath_ThrowsInvalidOperationException + - IntegrationTest_InvalidArgument_ShowsError + children: + - BuildMark-Context-InvalidArgs + + - id: BuildMark-Cli-ExitCode + title: The Cli subsystem shall return appropriate exit codes. + justification: | + Standard exit codes enable build automation systems and scripts to detect success + or failure conditions programmatically. + tests: + - Context_ExitCode_NoErrors_RemainsZero + - Context_WriteError_SetsExitCodeToOne + - IntegrationTest_InvalidArgument_ShowsError + children: + - BuildMark-Context-ExitCode diff --git a/docs/reqstream/cli/unit-context.yaml b/docs/reqstream/cli/unit-context.yaml new file mode 100644 index 0000000..f201240 --- /dev/null +++ b/docs/reqstream/cli/unit-context.yaml @@ -0,0 +1,89 @@ +--- +# Software Unit Requirements for the Context Class +# +# The Context class handles command-line argument parsing and program output. +# It is the primary interface between the user's command-line invocation and +# the tool's internal logic. + +sections: + - title: Context Unit Requirements + requirements: + - id: BuildMark-Context-ArgumentParsing + title: The Context class shall parse command-line arguments into structured properties. + justification: | + Provides a standardized approach to command-line argument parsing across all + DEMA Consulting DotNet Tools. Each recognized flag or value is stored as a + typed property so that the rest of the tool can read intent without re-parsing. + tests: + - Context_Create_EmptyArguments_CreatesValidContext + - Context_Create_LongVersionFlag_SetsVersionProperty + - Context_Create_ShortVersionFlag_SetsVersionProperty + - Context_Create_LongHelpFlag_SetsHelpProperty + - Context_Create_ShortHelpFlag_SetsHelpProperty + - Context_Create_QuestionMarkHelpFlag_SetsHelpProperty + - Context_Create_SilentFlag_SetsSilentProperty + - Context_Create_ValidateFlag_SetsValidateProperty + - Context_Create_BuildVersionArgument_SetsBuildVersionProperty + - Context_Create_ReportArgument_SetsReportFileProperty + - Context_Create_ReportDepthArgument_SetsReportDepthProperty + - Context_Create_IncludeKnownIssuesFlag_SetsIncludeKnownIssuesProperty + - Context_Create_ResultsArgument_SetsResultsFileProperty + - Context_Create_LogArgument_CreatesLogFile + - Context_Create_MultipleArguments_SetsAllPropertiesCorrectly + + - id: BuildMark-Context-InvalidArgs + title: The Context class shall reject unknown or malformed command-line arguments with a descriptive error. + justification: | + Providing clear feedback for invalid arguments helps users quickly correct + mistakes and prevents silent misconfiguration. + tests: + - Context_Create_UnsupportedArgument_ThrowsArgumentException + - Context_Create_BuildVersionWithoutValue_ThrowsArgumentException + - Context_Create_ReportWithoutValue_ThrowsArgumentException + - Context_Create_ReportDepthWithoutValue_ThrowsArgumentException + - Context_Create_ReportDepthWithNonIntegerValue_ThrowsArgumentException + - Context_Create_ReportDepthWithZeroValue_ThrowsArgumentException + - Context_Create_ReportDepthWithNegativeValue_ThrowsArgumentException + - Context_Create_ResultsWithoutValue_ThrowsArgumentException + - Context_Create_LogWithoutValue_ThrowsArgumentException + - Context_Create_InvalidLogFilePath_ThrowsInvalidOperationException + + - id: BuildMark-Context-Output + title: The Context class shall write output to the console and optionally to a log file. + justification: | + Provides persistent logging for debugging and audit trails, while also + allowing console output to be suppressed in automated environments. + tests: + - Context_WriteLine_NotSilent_WritesToConsole + - Context_WriteLine_Silent_DoesNotWriteToConsole + - Context_WriteLine_WithLogFile_WritesToLogFile + - Context_WriteError_WithLogFile_WritesToLogFile + - Context_Dispose_ClosesLogFileProperly + + - id: BuildMark-Context-Silent + title: The Context class shall suppress console output when the silent flag is set. + justification: | + Enables automated scripts and CI/CD pipelines to run the tool without + cluttering output logs. + tests: + - Context_Create_SilentFlag_SetsSilentProperty + - Context_WriteLine_Silent_DoesNotWriteToConsole + - Context_WriteError_Silent_DoesNotWriteToConsole + + - id: BuildMark-Context-ErrorOutput + title: The Context class shall write error messages to stderr. + justification: | + Error messages must be written to stderr so they remain visible to the user + without polluting stdout, which consumers may pipe or redirect for data capture. + tests: + - Context_WriteError_NotSilent_WritesToConsole + - Context_WriteError_SetsExitCodeToOne + + - id: BuildMark-Context-ExitCode + title: The Context class shall track errors and expose a non-zero exit code when errors have occurred. + justification: | + Callers (scripts, CI/CD pipelines) must be able to detect failure conditions + programmatically via the process exit code. + tests: + - Context_ExitCode_NoErrors_RemainsZero + - Context_WriteError_SetsExitCodeToOne diff --git a/docs/reqstream/ots-buildmark.yaml b/docs/reqstream/ots-buildmark.yaml new file mode 100644 index 0000000..8a58592 --- /dev/null +++ b/docs/reqstream/ots-buildmark.yaml @@ -0,0 +1,16 @@ +--- +sections: + - title: OTS Software Requirements + sections: + - title: BuildMark + requirements: + - id: BuildMark-OTS-BuildMark + title: BuildMark shall generate build-notes documentation from GitHub Actions metadata. + justification: | + DemaConsulting.BuildMark queries the GitHub API to capture workflow run details and + renders them as a markdown build-notes document included in the release artifacts. + It runs as part of the same CI pipeline that produces the TRX test results, so a + successful pipeline run is evidence that BuildMark executed without error. + tags: [ots] + tests: + - BuildMark_MarkdownReportGeneration diff --git a/docs/reqstream/ots-mstest.yaml b/docs/reqstream/ots-mstest.yaml new file mode 100644 index 0000000..b1533b8 --- /dev/null +++ b/docs/reqstream/ots-mstest.yaml @@ -0,0 +1,21 @@ +--- +sections: + - title: OTS Software Requirements + sections: + - title: MSTest + requirements: + - id: BuildMark-OTS-MSTest + title: MSTest shall execute unit tests and report results. + justification: | + MSTest (MSTest.TestFramework and MSTest.TestAdapter) is the unit-testing framework + used by the project. It discovers and runs all test methods and writes TRX result + files that feed into coverage reporting and requirements traceability. Passing tests + confirm the framework is functioning correctly. + tags: [ots] + tests: + - Context_Create_EmptyArguments_CreatesValidContext + - Context_Create_ShortVersionFlag_SetsVersionProperty + - Context_Create_LongVersionFlag_SetsVersionProperty + - Context_Create_SilentFlag_SetsSilentProperty + - Context_Create_ValidateFlag_SetsValidateProperty + - Context_Create_BuildVersionArgument_SetsBuildVersionProperty diff --git a/docs/reqstream/ots-reqstream.yaml b/docs/reqstream/ots-reqstream.yaml new file mode 100644 index 0000000..f5accc4 --- /dev/null +++ b/docs/reqstream/ots-reqstream.yaml @@ -0,0 +1,18 @@ +--- +sections: + - title: OTS Software Requirements + sections: + - title: ReqStream + requirements: + - id: BuildMark-OTS-ReqStream + title: ReqStream shall enforce that every requirement is linked to passing test evidence. + justification: | + DemaConsulting.ReqStream processes requirements.yaml and the TRX test-result files + to produce a requirements report, justifications document, and traceability matrix. + When run with --enforce, it exits with a non-zero code if any requirement lacks test + evidence, making unproven requirements a build-breaking condition. A successful + pipeline run with --enforce proves all requirements are covered and that ReqStream + is functioning. + tags: [ots] + tests: + - ReqStream_EnforcementMode diff --git a/docs/reqstream/ots-sarifmark.yaml b/docs/reqstream/ots-sarifmark.yaml new file mode 100644 index 0000000..0d7d7ef --- /dev/null +++ b/docs/reqstream/ots-sarifmark.yaml @@ -0,0 +1,17 @@ +--- +sections: + - title: OTS Software Requirements + sections: + - title: SarifMark + requirements: + - id: BuildMark-OTS-SarifMark + title: SarifMark shall convert CodeQL SARIF results into a markdown report. + justification: | + DemaConsulting.SarifMark reads the SARIF output produced by CodeQL code scanning + and renders it as a human-readable markdown document included in the release + artifacts. It runs in the same CI pipeline that produces the TRX test results, so + a successful pipeline run is evidence that SarifMark executed without error. + tags: [ots] + tests: + - SarifMark_SarifReading + - SarifMark_MarkdownReportGeneration diff --git a/docs/reqstream/ots-sonarmark.yaml b/docs/reqstream/ots-sonarmark.yaml new file mode 100644 index 0000000..12e376c --- /dev/null +++ b/docs/reqstream/ots-sonarmark.yaml @@ -0,0 +1,19 @@ +--- +sections: + - title: OTS Software Requirements + sections: + - title: SonarMark + requirements: + - id: BuildMark-OTS-SonarMark + title: SonarMark shall generate a SonarCloud quality report. + justification: | + DemaConsulting.SonarMark retrieves quality-gate and metrics data from SonarCloud + and renders it as a markdown document included in the release artifacts. It runs + in the same CI pipeline that produces the TRX test results, so a successful + pipeline run is evidence that SonarMark executed without error. + tags: [ots] + tests: + - SonarMark_QualityGateRetrieval + - SonarMark_IssuesRetrieval + - SonarMark_HotSpotsRetrieval + - SonarMark_MarkdownReportGeneration diff --git a/docs/reqstream/ots-versionmark.yaml b/docs/reqstream/ots-versionmark.yaml new file mode 100644 index 0000000..bc011ca --- /dev/null +++ b/docs/reqstream/ots-versionmark.yaml @@ -0,0 +1,17 @@ +--- +sections: + - title: OTS Software Requirements + sections: + - title: VersionMark + requirements: + - id: BuildMark-OTS-VersionMark + title: VersionMark shall publish captured tool-version information. + justification: | + DemaConsulting.VersionMark reads version metadata for each dotnet tool used in the + pipeline and writes a versions markdown document included in the release artifacts. + It runs in the same CI pipeline that produces the TRX test results, so a successful + pipeline run is evidence that VersionMark executed without error. + tags: [ots] + tests: + - VersionMark_CapturesVersions + - VersionMark_GeneratesMarkdownReport diff --git a/docs/reqstream/platform-requirements.yaml b/docs/reqstream/platform-requirements.yaml new file mode 100644 index 0000000..8bc28b4 --- /dev/null +++ b/docs/reqstream/platform-requirements.yaml @@ -0,0 +1,96 @@ +--- +sections: + - title: Platform Support + requirements: + - id: BuildMark-Plt-Windows + title: The tool shall run on Windows operating systems. + justification: | + Windows support is essential for .NET developers working in Windows-centric + environments, including enterprise settings and teams using Visual Studio. This + ensures BuildMark serves the full spectrum of .NET development scenarios. + # Test source pattern "windows@" ensures these tests ran on Windows. + # This filtering is necessary to prove Windows OS functionality. + tests: + - windows@IntegrationTest_VersionFlag_OutputsVersion + - windows@IntegrationTest_HelpFlag_OutputsUsageInformation + - windows@IntegrationTest_ReportParameter_IsAccepted + - windows@BuildMark_MarkdownReportGeneration + - windows@BuildMark_GitIntegration + - windows@BuildMark_IssueTracking + - windows@BuildMark_KnownIssuesReporting + + - id: BuildMark-Plt-Linux + title: The tool shall run on Linux operating systems. + justification: | + Linux support is critical for modern DevOps practices and cloud-native development + where Linux-based CI/CD systems and containerized environments dominate. This + ensures BuildMark works seamlessly in contemporary .NET deployment scenarios. + # Test source pattern "ubuntu@" ensures these tests ran on Linux. + # This filtering is necessary to prove Linux OS functionality. + tests: + - ubuntu@IntegrationTest_VersionFlag_OutputsVersion + - ubuntu@IntegrationTest_HelpFlag_OutputsUsageInformation + - ubuntu@IntegrationTest_ReportParameter_IsAccepted + - ubuntu@BuildMark_MarkdownReportGeneration + - ubuntu@BuildMark_GitIntegration + - ubuntu@BuildMark_IssueTracking + - ubuntu@BuildMark_KnownIssuesReporting + + - id: BuildMark-Plt-MacOS + title: The tool shall run on macOS operating systems. + justification: | + macOS support is essential for developers working on Apple platforms. This ensures + BuildMark serves the full spectrum of .NET development scenarios including macOS-based + CI/CD agents and developer workstations. + # Test source pattern "macos@" ensures these tests ran on macOS. + # This filtering is necessary to prove macOS functionality. + tests: + - macos@IntegrationTest_VersionFlag_OutputsVersion + - macos@IntegrationTest_HelpFlag_OutputsUsageInformation + - macos@IntegrationTest_ReportParameter_IsAccepted + - macos@BuildMark_MarkdownReportGeneration + - macos@BuildMark_GitIntegration + - macos@BuildMark_IssueTracking + - macos@BuildMark_KnownIssuesReporting + + - id: BuildMark-Plt-Net8 + title: The tool shall support .NET 8.0 runtime. + justification: | + .NET 8.0 is a Long-Term Support (LTS) release with support through November 2026. + Supporting this version ensures BuildMark remains usable for organizations following + Microsoft's LTS support lifecycle and requiring stability guarantees. + # Test source pattern "dotnet8.x@" ensures these tests ran on .NET 8.0. + # This filtering is necessary to prove .NET 8.0 runtime support. + tests: + - dotnet8.x@BuildMark_MarkdownReportGeneration + - dotnet8.x@BuildMark_GitIntegration + - dotnet8.x@BuildMark_IssueTracking + - dotnet8.x@BuildMark_KnownIssuesReporting + + - id: BuildMark-Plt-Net9 + title: The tool shall support .NET 9.0 runtime. + justification: | + .NET 9.0 is a Standard Term Support (STS) release with support through May 2026. + Supporting this version provides users access to the latest .NET features and + performance improvements for teams who prefer newer releases. + # Test source pattern "dotnet9.x@" ensures these tests ran on .NET 9.0. + # This filtering is necessary to prove .NET 9.0 runtime support. + tests: + - dotnet9.x@BuildMark_MarkdownReportGeneration + - dotnet9.x@BuildMark_GitIntegration + - dotnet9.x@BuildMark_IssueTracking + - dotnet9.x@BuildMark_KnownIssuesReporting + + - id: BuildMark-Plt-Net10 + title: The tool shall support .NET 10.0 runtime. + justification: | + .NET 10.0 is the next Long-Term Support (LTS) release planned for November 2025. + Early support ensures BuildMark remains current as users transition to this new + LTS version and provides forward compatibility guarantees. + # Test source pattern "dotnet10.x@" ensures these tests ran on .NET 10.0. + # This filtering is necessary to prove .NET 10.0 runtime support. + tests: + - dotnet10.x@BuildMark_MarkdownReportGeneration + - dotnet10.x@BuildMark_GitIntegration + - dotnet10.x@BuildMark_IssueTracking + - dotnet10.x@BuildMark_KnownIssuesReporting diff --git a/docs/reqstream/repo-connectors/subsystem-repo-connectors.yaml b/docs/reqstream/repo-connectors/subsystem-repo-connectors.yaml new file mode 100644 index 0000000..3e1ea67 --- /dev/null +++ b/docs/reqstream/repo-connectors/subsystem-repo-connectors.yaml @@ -0,0 +1,66 @@ +--- +# RepoConnectors Subsystem Requirements +# +# PURPOSE: +# - Define requirements for the BuildMark RepoConnectors subsystem +# - The RepoConnectors subsystem spans GitHubRepoConnector.cs, MockRepoConnector.cs, +# RepoConnectorFactory.cs, and ProcessRunner.cs +# - Subsystem requirements describe the externally visible repository connector behavior + +sections: + - title: RepoConnectors Subsystem Requirements + requirements: + - id: BuildMark-RepoConnectors-GitHubConnector + title: >- + The RepoConnectors subsystem shall provide a GitHub repository connector for retrieving + build information. + justification: | + Generating build notes from GitHub repositories requires a connector that can + authenticate to the GitHub API, retrieve commits, releases, tags, pull requests, + and issues, and assemble them into structured build information. The GitHub + connector satisfies this need for teams using GitHub as their source repository. + tests: + - GitHubRepoConnector_GetBuildInformationAsync_WithMockedData_ReturnsValidBuildInformation + - GitHubRepoConnector_GetBuildInformationAsync_WithMultipleVersions_SelectsCorrectPreviousVersionAndGeneratesChangelogLink + - GitHubRepoConnector_GetBuildInformationAsync_WithPullRequests_GathersChangesCorrectly + - GitHubRepoConnector_GetBuildInformationAsync_WithOpenIssues_IdentifiesKnownIssues + - GitHubRepoConnector_GetBuildInformationAsync_ReleaseVersion_SkipsAllPreReleases + children: + - BuildMark-GitHub-BuildInformation + - BuildMark-GitHub-GraphQLClient + + - id: BuildMark-RepoConnectors-MockConnector + title: The RepoConnectors subsystem shall provide a mock connector for testing and development. + justification: | + A mock connector enables unit testing of build information processing logic + without requiring an actual GitHub repository connection, ensuring tests are + fast, deterministic, and independent of external services. + tests: + - MockRepoConnector_Constructor_CreatesInstance + - MockRepoConnector_ImplementsInterface + - MockRepoConnector_GetBuildInformationAsync_ReturnsExpectedVersion + - MockRepoConnector_GetBuildInformationAsync_ReturnsCompleteInformation + + - id: BuildMark-RepoConnectors-ProcessRunner + title: The RepoConnectors subsystem shall provide a process execution utility for running shell commands. + justification: | + The RepoConnectors subsystem needs to execute shell commands (e.g., git, gh CLI) + to retrieve repository information and authentication tokens. The ProcessRunner + utility provides a consistent, testable interface for process execution with + proper error handling. + tests: + - ProcessRunner_TryRunAsync_WithValidCommand_ReturnsOutput + - ProcessRunner_TryRunAsync_WithInvalidCommand_ReturnsNull + - ProcessRunner_TryRunAsync_WithNonZeroExitCode_ReturnsNull + - ProcessRunner_RunAsync_WithValidCommand_ReturnsOutput + - ProcessRunner_RunAsync_WithFailingCommand_ThrowsException + + - id: BuildMark-RepoConnectors-Factory + title: The RepoConnectors subsystem shall provide a factory for creating the appropriate repository connector. + justification: | + A factory simplifies connector creation and encapsulates the logic for selecting + the correct connector implementation, enabling future extensibility with additional + repository connector types. + tests: + - RepoConnectorFactory_Create_ReturnsConnector + - RepoConnectorFactory_Create_ReturnsGitHubConnectorForThisRepo diff --git a/docs/reqstream/repo-connectors/unit-github-repo-connector.yaml b/docs/reqstream/repo-connectors/unit-github-repo-connector.yaml new file mode 100644 index 0000000..c27bc32 --- /dev/null +++ b/docs/reqstream/repo-connectors/unit-github-repo-connector.yaml @@ -0,0 +1,49 @@ +--- +# Software Unit Requirements for the GitHubRepoConnector Class +# +# The GitHubRepoConnector class connects to GitHub using the GraphQL API to +# retrieve commits, releases, tags, pull requests, and issues, assembling them +# into structured BuildInformation for report generation. + +sections: + - title: GitHubRepoConnector Unit Requirements + requirements: + - id: BuildMark-GitHub-BuildInformation + title: The GitHubRepoConnector class shall retrieve build information from a GitHub repository. + justification: | + The primary purpose of the GitHubRepoConnector is to assemble BuildInformation + from GitHub repository data. It must correctly identify the current version tag, + the baseline (previous) version tag, and the changes between them, correctly + handling pre-release tags and version selection edge cases. + tests: + - GitHubRepoConnector_GetBuildInformationAsync_WithMockedData_ReturnsValidBuildInformation + - GitHubRepoConnector_GetBuildInformationAsync_WithMultipleVersions_SelectsCorrectPreviousVersionAndGeneratesChangelogLink + - GitHubRepoConnector_GetBuildInformationAsync_WithPullRequests_GathersChangesCorrectly + - GitHubRepoConnector_GetBuildInformationAsync_WithOpenIssues_IdentifiesKnownIssues + - GitHubRepoConnector_GetBuildInformationAsync_ReleaseVersion_SkipsAllPreReleases + - GitHubRepoConnector_GetBuildInformationAsync_PreReleaseWithSameCommitHash_SkipsToNextDifferentHash + - GitHubRepoConnector_GetBuildInformationAsync_PreReleaseNotInHistory_UsesLatestDifferentHash + - GitHubRepoConnector_GetBuildInformationAsync_PreReleaseAllPreviousSameHash_ReturnsNullBaseline + - GitHubRepoConnector_GetBuildInformationAsync_WithDuplicateMergeCommitSha_DoesNotThrow + - GitHubRepoConnector_ImplementsInterface_ReturnsTrue + + - id: BuildMark-GitHub-GraphQLClient + title: The GitHubRepoConnector class shall use a GraphQL client for GitHub API interactions. + justification: | + The GitHub GraphQL API provides efficient access to repository data including + commits, releases, tags, pull requests, and issues with minimal API calls. + The GraphQL client handles pagination, error handling, and response parsing + to provide reliable data retrieval from the GitHub API. + tests: + - GitHubGraphQLClient_GetCommitsAsync_ValidResponse_ReturnsCommitShas + - GitHubGraphQLClient_GetCommitsAsync_WithPagination_ReturnsAllCommits + - GitHubGraphQLClient_GetReleasesAsync_ValidResponse_ReturnsReleaseTagNames + - GitHubGraphQLClient_GetReleasesAsync_WithPagination_ReturnsAllReleases + - GitHubGraphQLClient_GetAllTagsAsync_ValidResponse_ReturnsTagNodes + - GitHubGraphQLClient_GetAllTagsAsync_WithPagination_ReturnsAllTags + - GitHubGraphQLClient_GetPullRequestsAsync_ValidResponse_ReturnsPullRequests + - GitHubGraphQLClient_GetPullRequestsAsync_WithPagination_ReturnsAllPullRequests + - GitHubGraphQLClient_GetAllIssuesAsync_ValidResponse_ReturnsIssues + - GitHubGraphQLClient_GetAllIssuesAsync_WithPagination_ReturnsAllIssues + - GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_ValidResponse_ReturnsIssueIds + - GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_WithPagination_ReturnsAllIssues diff --git a/docs/reqstream/self-test/subsystem-self-test.yaml b/docs/reqstream/self-test/subsystem-self-test.yaml new file mode 100644 index 0000000..1cdc64c --- /dev/null +++ b/docs/reqstream/self-test/subsystem-self-test.yaml @@ -0,0 +1,43 @@ +--- +# SelfTest Subsystem Requirements +# +# PURPOSE: +# - Define requirements for the BuildMark SelfTest subsystem +# - The SelfTest subsystem spans Validation.cs (self-validation test execution) +# - Subsystem requirements describe the self-validation mechanism for tool qualification +# in regulated environments + +sections: + - title: SelfTest Subsystem Requirements + requirements: + - id: BuildMark-SelfTest-Qualification + title: The tool shall provide a self-validation mechanism to qualify the tool in its deployment environment. + justification: | + In regulated environments, tool qualification evidence is required to demonstrate + that the tool functions correctly in its deployment environment before it is used + to generate compliance artifacts. The SelfTest subsystem provides a built-in + self-validation suite that exercises core behaviors and produces a pass/fail + summary, enabling quality assurance teams to obtain tool qualification evidence + without requiring a separate test harness. + tests: + - Validation_Run_WithTrxResultsFile_WritesTrxFile + - Validation_Run_WithXmlResultsFile_WritesJUnitFile + - IntegrationTest_ValidateFlag_RunsSelfValidation + children: + - BuildMark-Validation-Run + + - id: BuildMark-SelfTest-ResultsOutput + title: The tool shall write self-validation results to a standard test result file when --results is provided. + justification: | + CI/CD pipelines and requirements traceability tools (such as ReqStream) consume + test result files in standard formats. By supporting both TRX (MSTest) and JUnit + XML output, the SelfTest subsystem enables self-validation results to be fed + directly into pipeline tooling and traceability reports without additional + conversion steps, satisfying audit trail requirements. + tests: + - Validation_Run_WithTrxResultsFile_WritesTrxFile + - Validation_Run_WithXmlResultsFile_WritesJUnitFile + - IntegrationTest_ResultsParameter_IsAccepted + children: + - BuildMark-Validation-TrxOutput + - BuildMark-Validation-JUnitOutput diff --git a/docs/reqstream/self-test/unit-validation.yaml b/docs/reqstream/self-test/unit-validation.yaml new file mode 100644 index 0000000..eac8a47 --- /dev/null +++ b/docs/reqstream/self-test/unit-validation.yaml @@ -0,0 +1,40 @@ +--- +# Software Unit Requirements for the Validation Class +# +# The Validation class executes the BuildMark self-validation test suite and +# writes results to standard test result files (TRX or JUnit XML format). + +sections: + - title: Validation Unit Requirements + requirements: + - id: BuildMark-Validation-Run + title: The Validation class shall execute self-validation tests and produce a summary report. + justification: | + Regulated environments require tool qualification evidence that the tool functions + correctly in the specific deployment environment. The Validation class exercises + core BuildMark behaviors and produces a pass/fail summary to support tool + qualification activities. + tests: + - Validation_Run_WithTrxResultsFile_WritesTrxFile + - Validation_Run_WithXmlResultsFile_WritesJUnitFile + + - id: BuildMark-Validation-TrxOutput + title: The Validation class shall write TRX format test results when a .trx results file is specified. + justification: | + TRX format support enables integration with Microsoft test tooling, Visual + Studio Test Explorer, and Azure DevOps pipelines, providing native support + for .NET development environments. + tests: + - Validation_Run_WithTrxResultsFile_WritesTrxFile + - Validation_Run_WithUnsupportedResultsFileExtension_ShowsError + + - id: BuildMark-Validation-JUnitOutput + title: The Validation class shall write JUnit XML format test results when an .xml results file is specified. + justification: | + JUnit format is a widely-supported standard across many CI/CD platforms and + testing tools. Supporting this format ensures BuildMark can integrate with + diverse toolchains beyond the Microsoft ecosystem. + tests: + - Validation_Run_WithXmlResultsFile_WritesJUnitFile + - Validation_Run_WithUnsupportedResultsFileExtension_ShowsError + - Validation_Run_WithInvalidResultsFilePath_ShowsError diff --git a/docs/reqstream/unit-program.yaml b/docs/reqstream/unit-program.yaml new file mode 100644 index 0000000..96f507c --- /dev/null +++ b/docs/reqstream/unit-program.yaml @@ -0,0 +1,48 @@ +--- +# Software Unit Requirements for the Program Class +# +# The Program class is the main entry point for BuildMark. It creates a Context +# from command-line arguments, dispatches to the appropriate logic based on the +# flags (version, help, validate, report), and returns the exit code. + +sections: + - title: Program Unit Requirements + requirements: + - id: BuildMark-Program-Version + title: The Program class shall support -v and --version flags to display version information. + justification: | + Users need to quickly identify the version of the tool they are using for + troubleshooting and compatibility verification. + tests: + - Program_Run_VersionFlag_OutputsVersionToConsole + - Program_Version_ReturnsValidVersion + - IntegrationTest_VersionFlag_OutputsVersion + + - id: BuildMark-Program-Help + title: The Program class shall support -?, -h, and --help flags to display usage information. + justification: | + Users need access to command-line usage documentation without requiring + external resources. + tests: + - Program_Run_HelpFlag_OutputsHelpMessage + - IntegrationTest_HelpFlag_OutputsUsageInformation + + - id: BuildMark-Program-Validate + title: The Program class shall support --validate flag to invoke the self-validation framework. + justification: | + Provides a built-in mechanism to verify the tool is functioning correctly + in the deployment environment. + tests: + - Program_Run_ValidateFlag_OutputsValidationMessage + - IntegrationTest_ValidateFlag_RunsSelfValidation + + - id: BuildMark-Program-Report + title: The Program class shall generate build notes markdown reports when --report is specified. + justification: | + Report generation is the primary purpose of the BuildMark tool. The Program + class orchestrates the repository connector, gathering of build information, + and generation of the output markdown report. + tests: + - Program_Run_ReportWithIncludeKnownIssuesFlag_GeneratesReportWithKnownIssues + - BuildMark_MarkdownReportGeneration + - IntegrationTest_ReportParameter_IsAccepted diff --git a/docs/reqstream/utilities/subsystem-utilities.yaml b/docs/reqstream/utilities/subsystem-utilities.yaml new file mode 100644 index 0000000..4543fa8 --- /dev/null +++ b/docs/reqstream/utilities/subsystem-utilities.yaml @@ -0,0 +1,25 @@ +--- +# Utilities Subsystem Requirements +# +# PURPOSE: +# - Define requirements for the BuildMark Utilities subsystem +# - The Utilities subsystem spans PathHelpers.cs (safe path-combination utilities) +# - Subsystem requirements describe the shared utility behavior available to all other subsystems + +sections: + - title: Utilities Subsystem Requirements + requirements: + - id: BuildMark-Utilities-SafePaths + title: The Utilities subsystem shall provide safe file path manipulation that prevents path traversal. + justification: | + The Utilities subsystem provides shared path utilities consumed by other subsystems. + When constructing file paths from caller-supplied inputs, the subsystem must reject + path traversal sequences (such as '..') and absolute paths to prevent unintended + file system access. This requirement captures the subsystem-level safety guarantee + that all consumers of the Utilities subsystem can rely upon. + tests: + - PathHelpers_SafePathCombine_ValidPaths_CombinesCorrectly + - PathHelpers_SafePathCombine_PathTraversalWithDoubleDots_ThrowsArgumentException + - PathHelpers_SafePathCombine_AbsolutePath_ThrowsArgumentException + children: + - BuildMark-PathHelpers-SafeCombine diff --git a/docs/reqstream/utilities/unit-path-helpers.yaml b/docs/reqstream/utilities/unit-path-helpers.yaml new file mode 100644 index 0000000..c675482 --- /dev/null +++ b/docs/reqstream/utilities/unit-path-helpers.yaml @@ -0,0 +1,23 @@ +--- +# Software Unit Requirements for the PathHelpers Class +# +# The PathHelpers class provides safe path-combination utilities that protect +# against path-traversal attacks by rejecting relative paths containing ".." +# or absolute paths when a relative path is expected. + +sections: + - title: PathHelpers Unit Requirements + requirements: + - id: BuildMark-PathHelpers-SafeCombine + title: The PathHelpers class shall combine paths safely, preventing path traversal. + justification: | + Prevents path-traversal vulnerabilities when constructing file paths from + user-supplied or external inputs. Paths containing ".." or rooted paths + must be rejected to ensure the combined path remains under the base directory. + tests: + - PathHelpers_SafePathCombine_ValidPaths_CombinesCorrectly + - PathHelpers_SafePathCombine_NullBasePath_ThrowsArgumentNullException + - PathHelpers_SafePathCombine_NullRelativePath_ThrowsArgumentNullException + - PathHelpers_SafePathCombine_PathTraversalWithDoubleDots_ThrowsArgumentException + - PathHelpers_SafePathCombine_DoubleDotsInMiddle_ThrowsArgumentException + - PathHelpers_SafePathCombine_AbsolutePath_ThrowsArgumentException diff --git a/requirements.yaml b/requirements.yaml index faaec1d..79630da 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -1,435 +1,19 @@ --- -sections: - - title: BuildMark Requirements - sections: - - title: Command-Line Interface - requirements: - - id: BuildMark-Cmd-Cli - title: The tool shall provide a command-line interface. - justification: | - A command-line interface is essential for BuildMark to integrate seamlessly into - automated build pipelines, CI/CD workflows, and scripting environments. This enables - developers and build systems to invoke the tool programmatically without requiring - a graphical user interface. - tests: - - IntegrationTest_VersionFlag_OutputsVersion - - IntegrationTest_HelpFlag_OutputsUsageInformation - - - id: BuildMark-Cmd-Version - title: The tool shall display version information when requested. - justification: | - Version information helps users identify which version of BuildMark they are running, - which is critical for debugging issues, ensuring compatibility, and tracking tool - updates across different environments. - tests: - - IntegrationTest_VersionFlag_OutputsVersion - - - id: BuildMark-Cmd-Help - title: The tool shall display help information when requested. - justification: | - Help information provides users with immediate access to usage instructions, available - commands, and parameter descriptions. This improves user experience and reduces the - learning curve for new users without requiring external documentation. - tests: - - IntegrationTest_HelpFlag_OutputsUsageInformation - - - id: BuildMark-Cmd-Silent - title: The tool shall support silent mode to suppress console output. - justification: | - Silent mode is essential for automated build environments where excessive console - output can clutter logs or interfere with parsing build results. This allows users - to control verbosity based on their specific use case. - tests: - - IntegrationTest_SilentFlag_SuppressesOutput - - - id: BuildMark-Cmd-Log - title: The tool shall support writing output to a log file. - justification: | - Log file support enables persistent storage of BuildMark output for audit trails, - troubleshooting, and post-build analysis. This is particularly valuable in automated - environments where console output may not be easily accessible. - tests: - - IntegrationTest_LogParameter_IsAccepted - - - id: BuildMark-Cmd-BuildVersion - title: The tool shall support specifying a build version. - justification: | - Specifying a build version allows users to override or supplement version information - from source control, enabling flexible version management strategies and supporting - scenarios where version numbers are determined externally. - tests: - - IntegrationTest_BuildVersionParameter_IsAccepted - - - id: BuildMark-Cmd-InvalidArgs - title: The tool shall validate command-line arguments. - justification: | - Argument validation prevents misuse of the tool and provides clear error messages - when invalid inputs are provided. This improves reliability, helps users identify - configuration errors early, and prevents unexpected behavior in automated workflows. - tests: - - IntegrationTest_InvalidArgument_ShowsError - - Context_Create_UnsupportedArgument_ThrowsArgumentException - - Context_Create_BuildVersionWithoutValue_ThrowsArgumentException - - Context_Create_ReportWithoutValue_ThrowsArgumentException - - Context_Create_ReportDepthWithoutValue_ThrowsArgumentException - - Context_Create_ReportDepthWithNonIntegerValue_ThrowsArgumentException - - Context_Create_ReportDepthWithZeroValue_ThrowsArgumentException - - Context_Create_ReportDepthWithNegativeValue_ThrowsArgumentException - - Context_Create_ResultsWithoutValue_ThrowsArgumentException - - Context_Create_LogWithoutValue_ThrowsArgumentException - - - id: BuildMark-Cmd-FilePaths - title: The tool shall handle invalid file paths gracefully. - justification: | - Graceful handling of invalid file paths prevents cryptic error messages and ensures - the tool fails safely when given incorrect paths. This improves user experience and - makes troubleshooting easier in production environments. - tests: - - Context_Create_InvalidLogFilePath_ThrowsInvalidOperationException - - - id: BuildMark-Cmd-ExitCode - title: The tool shall return appropriate exit codes. - justification: | - Standard exit codes enable build automation systems and scripts to detect success - or failure conditions programmatically. This is fundamental for proper integration - into CI/CD pipelines and automated workflows. - tests: - - Context_ExitCode_NoErrors_RemainsZero - - Context_WriteError_SetsExitCodeToOne - - - title: GitHub Integration - requirements: - - id: BuildMark-GH-BuildNotes - title: The tool shall generate build notes from GitHub repositories. - justification: | - Generating build notes from GitHub repositories automates the documentation of - changes between releases. This saves significant time during release processes and - ensures consistency in release documentation by deriving information directly from - source control history. - tests: - - BuildMark_GitIntegration - - BuildMark_MarkdownReportGeneration - - - id: BuildMark-GH-IssueTracking - title: The tool shall track issues and pull requests from GitHub. - justification: | - Tracking issues and pull requests provides traceability between code changes and - work items, enabling comprehensive release notes that link features, bug fixes, and - improvements to their corresponding GitHub issues and pull requests. - tests: - - BuildMark_IssueTracking - - - id: BuildMark-GH-VersionTags - title: The tool shall identify changes between version tags. - justification: | - Identifying changes between version tags enables differential release notes that - accurately capture what changed in each version. This is essential for semantic - versioning workflows and helps users understand the scope of changes between releases. - tests: - - BuildMark_GitIntegration - - - title: Report Generation - requirements: - - id: BuildMark-Rpt-Markdown - title: The tool shall generate markdown reports. - justification: | - Markdown is a widely-adopted, human-readable format that works seamlessly with - GitHub, documentation systems, and static site generators. Generating reports in - markdown format ensures broad compatibility and easy integration into existing - documentation workflows. - tests: - - BuildMark_MarkdownReportGeneration - - IntegrationTest_ReportParameter_IsAccepted - - - id: BuildMark-Rpt-Depth - title: The tool shall support configurable report depth. - justification: | - Configurable report depth allows BuildMark output to be embedded within existing - documentation structures by adjusting heading levels. This flexibility ensures - reports integrate properly regardless of the document hierarchy. - tests: - - IntegrationTest_ReportDepthParameter_IsAccepted - - BuildInformation_ToMarkdown_RespectsCustomHeadingDepth - - - id: BuildMark-Rpt-VersionInfo - title: The tool shall report version information in build notes. - justification: | - Version information clearly identifies which release the build notes describe, - providing essential context for users reviewing changes and enabling proper - organization of release documentation. - tests: - - BuildMark_MarkdownReportGeneration - - - id: BuildMark-Rpt-Changes - title: The tool shall report changes in build notes. - justification: | - Reporting changes documents new features and enhancements introduced in each - release, helping users understand the evolution of the software and make informed - decisions about upgrading. - tests: - - BuildMark_MarkdownReportGeneration - - BuildInformation_ToMarkdown_DisplaysNAForEmptyChanges - - - id: BuildMark-Rpt-BugFixes - title: The tool shall report bug fixes in build notes. - justification: | - Documenting bug fixes informs users about resolved issues, demonstrates ongoing - maintenance, and helps users determine if specific problems they encountered have - been addressed in newer versions. - tests: - - BuildMark_MarkdownReportGeneration - - BuildInformation_ToMarkdown_DisplaysNAForEmptyBugs - - - id: BuildMark-Rpt-KnownIssues - title: The tool shall support including known issues in build notes. - justification: | - Disclosing known issues in release notes promotes transparency, helps users avoid - known pitfalls, and manages expectations about current limitations. This improves - user trust and reduces support burden. - tests: - - BuildMark_KnownIssuesReporting - - - id: BuildMark-Rpt-VersionRange - title: The tool shall support filtering build notes by version range. - justification: | - Version range filtering enables generation of cumulative release notes covering - multiple versions or focused notes for specific releases. This flexibility supports - various documentation scenarios and user needs. - tests: - - BuildMark_MarkdownReportGeneration - - - id: BuildMark-Rpt-Hyperlinks - title: The tool shall include hyperlinks to issues and pull requests. - justification: | - Hyperlinks provide direct navigation to detailed information about changes, - enabling users to investigate specific items of interest and maintaining - traceability between release notes and source repository work items. - tests: - - BuildMark_MarkdownReportGeneration - - BuildInformation_ToMarkdown_IncludesIssueLinks - - BuildInformation_ToMarkdown_IncludesFullChangelogWhenLinkPresent - - - id: BuildMark-Rpt-Structure - title: The tool shall format build notes with proper markdown structure. - justification: | - Proper markdown structure ensures reports render correctly across different - markdown processors and documentation platforms. Well-structured documents are - more readable, professional, and maintainable. - tests: - - BuildMark_MarkdownReportGeneration - - BuildInformation_ToMarkdown_RespectsCustomHeadingDepth - - BuildInformation_ToMarkdown_UsesBulletLists - - BuildInformation_ToMarkdown_HandlesFirstReleaseWithNA - - BuildInformation_ToMarkdown_ExcludesFullChangelogWhenNoBaseline - - - title: Validation and Testing - requirements: - - id: BuildMark-Val-SelfValidation - title: The tool shall support self-validation mode. - justification: | - Self-validation mode allows users to validate the tool's functionality in their - environment, providing evidence that the user's environment does not introduce - unexpected behaviors, and giving users evidence they can rely on the tool's output. - tests: - - IntegrationTest_ValidateFlag_RunsSelfValidation - - - id: BuildMark-Val-ResultsFiles - title: The tool shall write validation results to test result files. - justification: | - Writing validation results to files enables integration with testing frameworks, - CI/CD pipelines, and reporting tools. This allows BuildMark's validation results - to be tracked, analyzed, and reported alongside other test metrics. - tests: - - IntegrationTest_ResultsParameter_IsAccepted - - - id: BuildMark-Val-TrxFormat - title: The tool shall support TRX format for test results. - justification: | - TRX format support enables integration with Microsoft test tooling and Visual - Studio Test Explorer, providing native support for .NET development environments - and Azure DevOps pipelines. - tests: - - IntegrationTest_ResultsParameter_IsAccepted - - - id: BuildMark-Val-JUnitFormat - title: The tool shall support JUnit format for test results. - justification: | - JUnit format is a widely-supported standard across many CI/CD platforms and - testing tools. Supporting this format ensures BuildMark can integrate with diverse - toolchains beyond the Microsoft ecosystem. - tests: - - IntegrationTest_ResultsParameter_IsAccepted - - - title: Platform Support - requirements: - - id: BuildMark-Plt-Windows - title: The tool shall run on Windows operating systems. - justification: | - Windows support is essential for .NET developers working in Windows-centric - environments, including enterprise settings and teams using Visual Studio. This - ensures BuildMark serves the full spectrum of .NET development scenarios. - # Test source pattern "windows@" ensures these tests ran on Windows. - # This filtering is necessary to prove Windows OS functionality. - tests: - - windows@IntegrationTest_VersionFlag_OutputsVersion - - windows@IntegrationTest_HelpFlag_OutputsUsageInformation - - windows@IntegrationTest_ReportParameter_IsAccepted - - windows@BuildMark_MarkdownReportGeneration - - windows@BuildMark_GitIntegration - - windows@BuildMark_IssueTracking - - windows@BuildMark_KnownIssuesReporting - - - id: BuildMark-Plt-Linux - title: The tool shall run on Linux operating systems. - justification: | - Linux support is critical for modern DevOps practices and cloud-native development - where Linux-based CI/CD systems and containerized environments dominate. This - ensures BuildMark works seamlessly in contemporary .NET deployment scenarios. - # Test source pattern "ubuntu@" ensures these tests ran on Linux. - # This filtering is necessary to prove Linux OS functionality. - tests: - - ubuntu@IntegrationTest_VersionFlag_OutputsVersion - - ubuntu@IntegrationTest_HelpFlag_OutputsUsageInformation - - ubuntu@IntegrationTest_ReportParameter_IsAccepted - - ubuntu@BuildMark_MarkdownReportGeneration - - ubuntu@BuildMark_GitIntegration - - ubuntu@BuildMark_IssueTracking - - ubuntu@BuildMark_KnownIssuesReporting - - - id: BuildMark-Plt-MacOS - title: The tool shall run on macOS operating systems. - justification: | - macOS support is essential for developers working on Apple platforms. This ensures - BuildMark serves the full spectrum of .NET development scenarios including macOS-based - CI/CD agents and developer workstations. - # Test source pattern "macos@" ensures these tests ran on macOS. - # This filtering is necessary to prove macOS functionality. - tests: - - macos@IntegrationTest_VersionFlag_OutputsVersion - - macos@IntegrationTest_HelpFlag_OutputsUsageInformation - - macos@IntegrationTest_ReportParameter_IsAccepted - - macos@BuildMark_MarkdownReportGeneration - - macos@BuildMark_GitIntegration - - macos@BuildMark_IssueTracking - - macos@BuildMark_KnownIssuesReporting - - - id: BuildMark-Plt-Net8 - title: The tool shall support .NET 8.0 runtime. - justification: | - .NET 8.0 is a Long-Term Support (LTS) release with support through November 2026. - Supporting this version ensures BuildMark remains usable for organizations following - Microsoft's LTS support lifecycle and requiring stability guarantees. - # Test source pattern "dotnet8.x@" ensures these tests ran on .NET 8.0. - # This filtering is necessary to prove .NET 8.0 runtime support. - tests: - - dotnet8.x@BuildMark_MarkdownReportGeneration - - dotnet8.x@BuildMark_GitIntegration - - dotnet8.x@BuildMark_IssueTracking - - dotnet8.x@BuildMark_KnownIssuesReporting - - - id: BuildMark-Plt-Net9 - title: The tool shall support .NET 9.0 runtime. - justification: | - .NET 9.0 is a Standard Term Support (STS) release with support through May 2026. - Supporting this version provides users access to the latest .NET features and - performance improvements for teams who prefer newer releases. - # Test source pattern "dotnet9.x@" ensures these tests ran on .NET 9.0. - # This filtering is necessary to prove .NET 9.0 runtime support. - tests: - - dotnet9.x@BuildMark_MarkdownReportGeneration - - dotnet9.x@BuildMark_GitIntegration - - dotnet9.x@BuildMark_IssueTracking - - dotnet9.x@BuildMark_KnownIssuesReporting - - - id: BuildMark-Plt-Net10 - title: The tool shall support .NET 10.0 runtime. - justification: | - .NET 10.0 is the next Long-Term Support (LTS) release planned for November 2025. - Early support ensures BuildMark remains current as users transition to this new - LTS version and provides forward compatibility guarantees. - # Test source pattern "dotnet10.x@" ensures these tests ran on .NET 10.0. - # This filtering is necessary to prove .NET 10.0 runtime support. - tests: - - dotnet10.x@BuildMark_MarkdownReportGeneration - - dotnet10.x@BuildMark_GitIntegration - - dotnet10.x@BuildMark_IssueTracking - - dotnet10.x@BuildMark_KnownIssuesReporting - - - title: OTS Software - requirements: - - id: BuildMark-OTS-MSTest - title: MSTest shall execute unit tests and report results. - justification: | - MSTest (MSTest.TestFramework and MSTest.TestAdapter) is the unit-testing framework used - by the project. It discovers and runs all test methods and writes TRX result files that - feed into coverage reporting and requirements traceability. Passing tests confirm the - framework is functioning correctly. - tags: [ots] - tests: - - Context_Create_EmptyArguments_CreatesValidContext - - Context_Create_ShortVersionFlag_SetsVersionProperty - - Context_Create_LongVersionFlag_SetsVersionProperty - - Context_Create_SilentFlag_SetsSilentProperty - - Context_Create_ValidateFlag_SetsValidateProperty - - Context_Create_BuildVersionArgument_SetsBuildVersionProperty - - - id: BuildMark-OTS-ReqStream - title: ReqStream shall enforce that every requirement is linked to passing test evidence. - justification: | - DemaConsulting.ReqStream processes requirements.yaml and the TRX test-result files to - produce a requirements report, justifications document, and traceability matrix. When - run with --enforce, it exits with a non-zero code if any requirement lacks test evidence, - making unproven requirements a build-breaking condition. A successful pipeline run with - --enforce proves all requirements are covered and that ReqStream is functioning. - tags: [ots] - tests: - - ReqStream_EnforcementMode - - - id: BuildMark-OTS-BuildMark - title: BuildMark shall generate build-notes documentation from GitHub Actions metadata. - justification: | - DemaConsulting.BuildMark queries the GitHub API to capture workflow run details and - renders them as a markdown build-notes document included in the release artifacts. - It runs as part of the same CI pipeline that produces the TRX test results, so a - successful pipeline run is evidence that BuildMark executed without error. - tags: [ots] - tests: - - BuildMark_MarkdownReportGeneration - - - id: BuildMark-OTS-VersionMark - title: VersionMark shall publish captured tool-version information. - justification: | - DemaConsulting.VersionMark reads version metadata for each dotnet tool used in the - pipeline and writes a versions markdown document included in the release artifacts. - It runs in the same CI pipeline that produces the TRX test results, so a successful - pipeline run is evidence that VersionMark executed without error. - tags: [ots] - tests: - - VersionMark_CapturesVersions - - VersionMark_GeneratesMarkdownReport - - - id: BuildMark-OTS-SarifMark - title: SarifMark shall convert CodeQL SARIF results into a markdown report. - justification: | - DemaConsulting.SarifMark reads the SARIF output produced by CodeQL code scanning and - renders it as a human-readable markdown document included in the release artifacts. - It runs in the same CI pipeline that produces the TRX test results, so a successful - pipeline run is evidence that SarifMark executed without error. - tags: [ots] - tests: - - SarifMark_SarifReading - - SarifMark_MarkdownReportGeneration - - - id: BuildMark-OTS-SonarMark - title: SonarMark shall generate a SonarCloud quality report. - justification: | - DemaConsulting.SonarMark retrieves quality-gate and metrics data from SonarCloud and - renders it as a markdown document included in the release artifacts. It runs in the - same CI pipeline that produces the TRX test results, so a successful pipeline run is - evidence that SonarMark executed without error. - tags: [ots] - tests: - - SonarMark_QualityGateRetrieval - - SonarMark_IssuesRetrieval - - SonarMark_HotSpotsRetrieval - - SonarMark_MarkdownReportGeneration +includes: + - docs/reqstream/buildmark-system.yaml + - docs/reqstream/platform-requirements.yaml + - docs/reqstream/unit-program.yaml + - docs/reqstream/cli/subsystem-cli.yaml + - docs/reqstream/cli/unit-context.yaml + - docs/reqstream/self-test/subsystem-self-test.yaml + - docs/reqstream/self-test/unit-validation.yaml + - docs/reqstream/utilities/subsystem-utilities.yaml + - docs/reqstream/utilities/unit-path-helpers.yaml + - docs/reqstream/repo-connectors/subsystem-repo-connectors.yaml + - docs/reqstream/repo-connectors/unit-github-repo-connector.yaml + - 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/src/DemaConsulting.BuildMark/Context.cs b/src/DemaConsulting.BuildMark/Cli/Context.cs similarity index 100% rename from src/DemaConsulting.BuildMark/Context.cs rename to src/DemaConsulting.BuildMark/Cli/Context.cs diff --git a/src/DemaConsulting.BuildMark/Validation.cs b/src/DemaConsulting.BuildMark/SelfTest/Validation.cs similarity index 100% rename from src/DemaConsulting.BuildMark/Validation.cs rename to src/DemaConsulting.BuildMark/SelfTest/Validation.cs diff --git a/src/DemaConsulting.BuildMark/PathHelpers.cs b/src/DemaConsulting.BuildMark/Utilities/PathHelpers.cs similarity index 100% rename from src/DemaConsulting.BuildMark/PathHelpers.cs rename to src/DemaConsulting.BuildMark/Utilities/PathHelpers.cs diff --git a/test/DemaConsulting.BuildMark.Tests/ContextTests.cs b/test/DemaConsulting.BuildMark.Tests/Cli/ContextTests.cs similarity index 100% rename from test/DemaConsulting.BuildMark.Tests/ContextTests.cs rename to test/DemaConsulting.BuildMark.Tests/Cli/ContextTests.cs diff --git a/test/DemaConsulting.BuildMark.Tests/GitHubRepoConnectorTests.cs b/test/DemaConsulting.BuildMark.Tests/RepoConnectors/GitHub/GitHubRepoConnectorTests.cs similarity index 100% rename from test/DemaConsulting.BuildMark.Tests/GitHubRepoConnectorTests.cs rename to test/DemaConsulting.BuildMark.Tests/RepoConnectors/GitHub/GitHubRepoConnectorTests.cs diff --git a/test/DemaConsulting.BuildMark.Tests/MockRepoConnectorTests.cs b/test/DemaConsulting.BuildMark.Tests/RepoConnectors/MockRepoConnectorTests.cs similarity index 100% rename from test/DemaConsulting.BuildMark.Tests/MockRepoConnectorTests.cs rename to test/DemaConsulting.BuildMark.Tests/RepoConnectors/MockRepoConnectorTests.cs diff --git a/test/DemaConsulting.BuildMark.Tests/ProcessRunnerTests.cs b/test/DemaConsulting.BuildMark.Tests/RepoConnectors/ProcessRunnerTests.cs similarity index 100% rename from test/DemaConsulting.BuildMark.Tests/ProcessRunnerTests.cs rename to test/DemaConsulting.BuildMark.Tests/RepoConnectors/ProcessRunnerTests.cs diff --git a/test/DemaConsulting.BuildMark.Tests/RepoConnectorFactoryTests.cs b/test/DemaConsulting.BuildMark.Tests/RepoConnectors/RepoConnectorFactoryTests.cs similarity index 100% rename from test/DemaConsulting.BuildMark.Tests/RepoConnectorFactoryTests.cs rename to test/DemaConsulting.BuildMark.Tests/RepoConnectors/RepoConnectorFactoryTests.cs diff --git a/test/DemaConsulting.BuildMark.Tests/ValidationTests.cs b/test/DemaConsulting.BuildMark.Tests/SelfTest/ValidationTests.cs similarity index 100% rename from test/DemaConsulting.BuildMark.Tests/ValidationTests.cs rename to test/DemaConsulting.BuildMark.Tests/SelfTest/ValidationTests.cs diff --git a/test/DemaConsulting.BuildMark.Tests/PathHelpersTests.cs b/test/DemaConsulting.BuildMark.Tests/Utilities/PathHelpersTests.cs similarity index 100% rename from test/DemaConsulting.BuildMark.Tests/PathHelpersTests.cs rename to test/DemaConsulting.BuildMark.Tests/Utilities/PathHelpersTests.cs