From 7c2d7cb08bbe4ebb1d94abad783531a87730c3ce Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 3 Apr 2026 00:26:04 +0000 Subject: [PATCH 1/5] chore: update repository to comply with standards Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/8e4a84f0-5d37-4ea6-b125-222f17a55594 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .reviewmark.yaml | 61 ++++++------ docs/design/system.md | 96 +++++++++++++++++++ .../cli/{subsystem-cli.yaml => cli.yaml} | 0 .../cli/{unit-context.yaml => context.yaml} | 0 .../buildmark.yaml} | 0 .../{ots-mstest.yaml => ots/mstest.yaml} | 0 .../reqstream.yaml} | 0 .../sarifmark.yaml} | 0 .../sonarmark.yaml} | 0 .../versionmark.yaml} | 0 .../{unit-program.yaml => program.yaml} | 0 ...nector.yaml => github-repo-connector.yaml} | 0 ...o-connectors.yaml => repo-connectors.yaml} | 0 ...ubsystem-self-test.yaml => self-test.yaml} | 0 .../{unit-validation.yaml => validation.yaml} | 0 .../{buildmark-system.yaml => system.yaml} | 0 ...it-path-helpers.yaml => path-helpers.yaml} | 0 ...ubsystem-utilities.yaml => utilities.yaml} | 0 requirements.yaml | 32 +++---- 19 files changed, 143 insertions(+), 46 deletions(-) create mode 100644 docs/design/system.md rename docs/reqstream/cli/{subsystem-cli.yaml => cli.yaml} (100%) rename docs/reqstream/cli/{unit-context.yaml => context.yaml} (100%) rename docs/reqstream/{ots-buildmark.yaml => ots/buildmark.yaml} (100%) rename docs/reqstream/{ots-mstest.yaml => ots/mstest.yaml} (100%) rename docs/reqstream/{ots-reqstream.yaml => ots/reqstream.yaml} (100%) rename docs/reqstream/{ots-sarifmark.yaml => ots/sarifmark.yaml} (100%) rename docs/reqstream/{ots-sonarmark.yaml => ots/sonarmark.yaml} (100%) rename docs/reqstream/{ots-versionmark.yaml => ots/versionmark.yaml} (100%) rename docs/reqstream/{unit-program.yaml => program.yaml} (100%) rename docs/reqstream/repo-connectors/{unit-github-repo-connector.yaml => github-repo-connector.yaml} (100%) rename docs/reqstream/repo-connectors/{subsystem-repo-connectors.yaml => repo-connectors.yaml} (100%) rename docs/reqstream/self-test/{subsystem-self-test.yaml => self-test.yaml} (100%) rename docs/reqstream/self-test/{unit-validation.yaml => validation.yaml} (100%) rename docs/reqstream/{buildmark-system.yaml => system.yaml} (100%) rename docs/reqstream/utilities/{unit-path-helpers.yaml => path-helpers.yaml} (100%) rename docs/reqstream/utilities/{subsystem-utilities.yaml => utilities.yaml} (100%) diff --git a/.reviewmark.yaml b/.reviewmark.yaml index f9af4e7..4aadf9f 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -17,7 +17,7 @@ reviews: - id: BuildMark-Program title: Review of BuildMark Program Unit paths: - - "docs/reqstream/unit-program.yaml" + - "docs/reqstream/program.yaml" - "docs/design/program.md" - "src/**/Program.cs" - "test/**/ProgramTests.cs" @@ -25,7 +25,7 @@ reviews: - id: BuildMark-Context title: Review of BuildMark Context Unit paths: - - "docs/reqstream/cli/unit-context.yaml" + - "docs/reqstream/cli/context.yaml" - "docs/design/cli/context.md" - "src/**/Cli/Context.cs" - "test/**/Cli/ContextTests.cs" @@ -33,7 +33,7 @@ reviews: - id: BuildMark-Validation title: Review of BuildMark Validation Unit paths: - - "docs/reqstream/self-test/unit-validation.yaml" + - "docs/reqstream/self-test/validation.yaml" - "docs/design/self-test/validation.md" - "src/**/SelfTest/Validation.cs" - "test/**/SelfTest/ValidationTests.cs" @@ -41,7 +41,7 @@ reviews: - id: BuildMark-PathHelpers title: Review of BuildMark PathHelpers Unit paths: - - "docs/reqstream/utilities/unit-path-helpers.yaml" + - "docs/reqstream/utilities/path-helpers.yaml" - "docs/design/utilities/path-helpers.md" - "src/**/Utilities/PathHelpers.cs" - "test/**/Utilities/PathHelpersTests.cs" @@ -49,11 +49,11 @@ reviews: - id: BuildMark-GitHubRepoConnector title: Review of BuildMark GitHubRepoConnector Unit paths: - - "docs/reqstream/repo-connectors/unit-github-repo-connector.yaml" + - "docs/reqstream/repo-connectors/github-repo-connector.yaml" - "docs/design/repo-connectors/github-repo-connector.md" - - "src/**/GitHub/GitHubRepoConnector.cs" - - "src/**/GitHub/GitHubGraphQLClient.cs" - - "src/**/GitHub/GitHubGraphQLTypes.cs" + - "src/**/RepoConnectors/GitHubRepoConnector.cs" + - "src/**/RepoConnectors/GitHub/GitHubGraphQLClient.cs" + - "src/**/RepoConnectors/GitHub/GitHubGraphQLTypes.cs" - "test/**/RepoConnectors/GitHub/GitHubRepoConnectorTests.cs" - "test/**/RepoConnectors/GitHub/GitHubGraphQLClientFindIssueIdsTests.cs" - "test/**/RepoConnectors/GitHub/GitHubGraphQLClientGetAllIssuesTests.cs" @@ -69,7 +69,7 @@ reviews: - id: BuildMark-Cli title: Review of BuildMark Cli subsystem (command-line interface) paths: - - "docs/reqstream/cli/subsystem-cli.yaml" + - "docs/reqstream/cli/cli.yaml" - "docs/design/cli/cli.md" - "docs/design/cli/context.md" - "docs/design/program.md" @@ -77,39 +77,40 @@ reviews: - id: BuildMark-SelfTest title: Review of BuildMark SelfTest subsystem (self-validation) paths: - - "docs/reqstream/self-test/subsystem-self-test.yaml" + - "docs/reqstream/self-test/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/reqstream/utilities/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 + - "docs/reqstream/repo-connectors/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/system.yaml" - "docs/reqstream/platform-requirements.yaml" - "docs/design/introduction.md" + - "docs/design/system.md" - "test/**/IntegrationTests.cs" - "test/**/Runner.cs" - "test/**/AssemblyInfo.cs" @@ -127,12 +128,12 @@ reviews: - "docs/reqstream/**/*.yaml" # OTS dependency reviews - - id: OTS-Dependencies + - id: BuildMark-OTS 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" + - "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/system.md b/docs/design/system.md new file mode 100644 index 0000000..9bca4a2 --- /dev/null +++ b/docs/design/system.md @@ -0,0 +1,96 @@ +# BuildMark System Design + +## Overview + +BuildMark is a .NET command-line tool that generates markdown build notes from +GitHub repository metadata. It queries GitHub's GraphQL API to retrieve commits, +issues, pull requests, and version tags, then formats the results as a structured +markdown report suitable for embedding in release documentation. + +## System Architecture + +BuildMark is composed of four subsystems and a top-level entry point: + +| Component | Kind | Responsibility | +|----------------------|-----------|----------------------------------------------------------| +| `Program` | Unit | Entry point; dispatches to handlers based on CLI flags | +| `Cli` | Subsystem | Command-line argument parsing and output channel control | +| `RepoConnectors` | Subsystem | Repository metadata retrieval via the GitHub GraphQL API | +| `SelfTest` | Subsystem | Built-in self-validation test framework | +| `Utilities` | Subsystem | Shared path combination helpers | + +## External Interfaces + +| Interface | Direction | Protocol / Format | +|-----------------|-----------|-----------------------------------------------------| +| Command line | Input | POSIX-style flags parsed by `Context` | +| GitHub GraphQL | Output | HTTPS POST to `https://api.github.com/graphql` | +| Markdown report | Output | File written to `--report` path, UTF-8 markdown | +| Log file | Output | Optional file written to `--log` path, plain text | +| Test results | Output | TRX or JUnit XML written to `--results` path | +| Exit code | Output | 0 = success, 1 = error | + +## Data Flow + +```text +[Command Line Args] + │ + ▼ + Context (Cli) ← parses flags, opens log/report files + │ + ▼ + Program.Run() + ├─ --version → writes version to stdout + ├─ --help → writes usage to stdout + ├─ --validate → Validation (SelfTest) → writes results to --results file + └─ (default) → ProcessBuildNotes() + │ + ▼ + RepoConnectorFactory + │ + ▼ + GitHubRepoConnector ←─── GitHub GraphQL API + │ + ▼ + BuildInformation.ToMarkdown() + │ + ▼ + [Markdown Report File] +``` + +## System-Wide Design Constraints + +- **Target framework**: .NET 8 and .NET 9 +- **Platform support**: Windows, Linux, macOS +- **Packaging**: Published as a .NET global tool (`dotnet tool install`) +- **Authentication**: GitHub token supplied via `GH_TOKEN` environment variable, + `GITHUB_TOKEN` environment variable, or `gh auth token` CLI fallback +- **No GUI**: All interaction is through the command line; no interactive prompts +- **Self-contained**: No external configuration files required for normal operation + +## Integration Patterns + +### GitHub GraphQL Client + +`GitHubRepoConnector` uses `GitHubGraphQLClient` to issue paginated GraphQL +queries over HTTPS. Authentication is via `Authorization: bearer ` header. +The connector retrieves: + +- All tags (for identifying version boundaries) +- Commits in the requested range +- Issues referenced by commits +- Pull requests in the requested range +- Releases (for known-issues data) + +### Self-Validation + +The `--validate` flag invokes `Validation.Run`, which exercises core tool +functionality using a `MockRepoConnector` and writes a standard TRX or JUnit XML +results file. This allows operators to verify the tool works correctly in their +environment without requiring a live GitHub connection. + +### Report Generation + +`BuildInformation.ToMarkdown` converts the in-memory build data model into a +markdown string. The heading depth is configurable via `--report-depth`, allowing +the report to be embedded at any level in a larger document. diff --git a/docs/reqstream/cli/subsystem-cli.yaml b/docs/reqstream/cli/cli.yaml similarity index 100% rename from docs/reqstream/cli/subsystem-cli.yaml rename to docs/reqstream/cli/cli.yaml diff --git a/docs/reqstream/cli/unit-context.yaml b/docs/reqstream/cli/context.yaml similarity index 100% rename from docs/reqstream/cli/unit-context.yaml rename to docs/reqstream/cli/context.yaml diff --git a/docs/reqstream/ots-buildmark.yaml b/docs/reqstream/ots/buildmark.yaml similarity index 100% rename from docs/reqstream/ots-buildmark.yaml rename to docs/reqstream/ots/buildmark.yaml diff --git a/docs/reqstream/ots-mstest.yaml b/docs/reqstream/ots/mstest.yaml similarity index 100% rename from docs/reqstream/ots-mstest.yaml rename to docs/reqstream/ots/mstest.yaml diff --git a/docs/reqstream/ots-reqstream.yaml b/docs/reqstream/ots/reqstream.yaml similarity index 100% rename from docs/reqstream/ots-reqstream.yaml rename to docs/reqstream/ots/reqstream.yaml diff --git a/docs/reqstream/ots-sarifmark.yaml b/docs/reqstream/ots/sarifmark.yaml similarity index 100% rename from docs/reqstream/ots-sarifmark.yaml rename to docs/reqstream/ots/sarifmark.yaml diff --git a/docs/reqstream/ots-sonarmark.yaml b/docs/reqstream/ots/sonarmark.yaml similarity index 100% rename from docs/reqstream/ots-sonarmark.yaml rename to docs/reqstream/ots/sonarmark.yaml diff --git a/docs/reqstream/ots-versionmark.yaml b/docs/reqstream/ots/versionmark.yaml similarity index 100% rename from docs/reqstream/ots-versionmark.yaml rename to docs/reqstream/ots/versionmark.yaml diff --git a/docs/reqstream/unit-program.yaml b/docs/reqstream/program.yaml similarity index 100% rename from docs/reqstream/unit-program.yaml rename to docs/reqstream/program.yaml diff --git a/docs/reqstream/repo-connectors/unit-github-repo-connector.yaml b/docs/reqstream/repo-connectors/github-repo-connector.yaml similarity index 100% rename from docs/reqstream/repo-connectors/unit-github-repo-connector.yaml rename to docs/reqstream/repo-connectors/github-repo-connector.yaml diff --git a/docs/reqstream/repo-connectors/subsystem-repo-connectors.yaml b/docs/reqstream/repo-connectors/repo-connectors.yaml similarity index 100% rename from docs/reqstream/repo-connectors/subsystem-repo-connectors.yaml rename to docs/reqstream/repo-connectors/repo-connectors.yaml diff --git a/docs/reqstream/self-test/subsystem-self-test.yaml b/docs/reqstream/self-test/self-test.yaml similarity index 100% rename from docs/reqstream/self-test/subsystem-self-test.yaml rename to docs/reqstream/self-test/self-test.yaml diff --git a/docs/reqstream/self-test/unit-validation.yaml b/docs/reqstream/self-test/validation.yaml similarity index 100% rename from docs/reqstream/self-test/unit-validation.yaml rename to docs/reqstream/self-test/validation.yaml diff --git a/docs/reqstream/buildmark-system.yaml b/docs/reqstream/system.yaml similarity index 100% rename from docs/reqstream/buildmark-system.yaml rename to docs/reqstream/system.yaml diff --git a/docs/reqstream/utilities/unit-path-helpers.yaml b/docs/reqstream/utilities/path-helpers.yaml similarity index 100% rename from docs/reqstream/utilities/unit-path-helpers.yaml rename to docs/reqstream/utilities/path-helpers.yaml diff --git a/docs/reqstream/utilities/subsystem-utilities.yaml b/docs/reqstream/utilities/utilities.yaml similarity index 100% rename from docs/reqstream/utilities/subsystem-utilities.yaml rename to docs/reqstream/utilities/utilities.yaml diff --git a/requirements.yaml b/requirements.yaml index 79630da..b5897be 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -1,19 +1,19 @@ --- includes: - - docs/reqstream/buildmark-system.yaml + - docs/reqstream/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 + - docs/reqstream/program.yaml + - docs/reqstream/cli/cli.yaml + - docs/reqstream/cli/context.yaml + - docs/reqstream/self-test/self-test.yaml + - docs/reqstream/self-test/validation.yaml + - docs/reqstream/utilities/utilities.yaml + - docs/reqstream/utilities/path-helpers.yaml + - docs/reqstream/repo-connectors/repo-connectors.yaml + - docs/reqstream/repo-connectors/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 From bbe6fb1fafde8a909f3b336806f84c5f13219377 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 3 Apr 2026 00:31:29 +0000 Subject: [PATCH 2/5] chore: remove OTS review from reviewmark Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/c54edaaa-b4b2-413e-83d8-acbe69fc2f92 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .reviewmark.yaml | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 4aadf9f..ef71ea1 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -127,13 +127,3 @@ reviews: - "requirements.yaml" - "docs/reqstream/**/*.yaml" - # OTS dependency reviews - - id: BuildMark-OTS - 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" From e02d6b74910b80bed009556475054fe17c7e650f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 3 Apr 2026 00:47:48 +0000 Subject: [PATCH 3/5] chore: fix trailing blank line in reviewmark.yaml Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/7842d36c-cd22-4ffc-bb58-e50eb2835a14 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .reviewmark.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/.reviewmark.yaml b/.reviewmark.yaml index ef71ea1..287af67 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -126,4 +126,3 @@ reviews: paths: - "requirements.yaml" - "docs/reqstream/**/*.yaml" - From cb1f6ffaeaa5bc70eae75c7647e31246c36ba755 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Thu, 2 Apr 2026 20:48:31 -0400 Subject: [PATCH 4/5] Update docs/design/system.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/design/system.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/system.md b/docs/design/system.md index 9bca4a2..4052e22 100644 --- a/docs/design/system.md +++ b/docs/design/system.md @@ -36,7 +36,7 @@ BuildMark is composed of four subsystems and a top-level entry point: [Command Line Args] │ ▼ - Context (Cli) ← parses flags, opens log/report files + Context (Cli) ← parses flags, opens log file │ ▼ Program.Run() From 13fa03ddf7356b30842f48bc03d97e1595d8ce14 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 3 Apr 2026 00:51:09 +0000 Subject: [PATCH 5/5] docs: update target framework to include .NET 10 Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/97d1efaa-8375-4c1f-a442-d90455521989 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- docs/design/system.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/system.md b/docs/design/system.md index 4052e22..a94edd1 100644 --- a/docs/design/system.md +++ b/docs/design/system.md @@ -60,7 +60,7 @@ BuildMark is composed of four subsystems and a top-level entry point: ## System-Wide Design Constraints -- **Target framework**: .NET 8 and .NET 9 +- **Target framework**: .NET 8, .NET 9, and .NET 10 - **Platform support**: Windows, Linux, macOS - **Packaging**: Published as a .NET global tool (`dotnet tool install`) - **Authentication**: GitHub token supplied via `GH_TOKEN` environment variable,