feat: introduce .buildmark.yaml configuration support and align related documentation by Copilot · Pull Request #131 · demaconsulting/BuildMark

Copilot · 2026-04-08T09:57:40Z

Pull Request

Description

Introduces .buildmark.yaml configuration support for BuildMark and aligns the surrounding implementation, design documentation, user documentation, and requirements with the current behavior.

This update also incorporates follow-up review feedback by correcting stale configuration and version documentation, removing obsolete requirements content, fixing a portable shell-command test case, removing unused usings, and removing the UTF-8 BOM from the push workflow file.

Type of Change

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Documentation update
Code quality improvement

Related Issues

Pre-Submission Checklist

Before submitting this pull request, ensure you have completed the following:

Build and Test

Code builds successfully: dotnet build --configuration Release
All tests pass: dotnet test --configuration Release
Self-validation tests pass:
dotnet run --project src/DemaConsulting.BuildMark --configuration Release --framework net10.0
--no-build -- --validate
Code produces zero warnings

Code Quality

Code formatting is correct: dotnet format --verify-no-changes
New code has appropriate XML documentation comments
Static analyzer warnings have been addressed

Quality Checks

Please run the following checks before submitting:

All linters pass: ./lint.sh (Unix/macOS) or cmd /c lint.bat / ./lint.bat (Windows)

Testing

Added unit tests for new functionality
Updated existing tests if behavior changed
All tests follow the AAA (Arrange, Act, Assert) pattern
Test coverage is maintained or improved

Documentation

Updated README.md (if applicable)
Updated ARCHITECTURE.md (if applicable)
Added code examples for new features (if applicable)
Updated requirements.yaml (if applicable)

Additional Notes

Key updates included in this PR:

Added .buildmark.yaml configuration support and related design/requirements coverage
Documented configuration-driven connector, section, and rule behavior
Added and documented configuration linting behavior
Corrected README and user guide examples to match implemented GitHub connector keys
Aligned design docs with the actual Version subsystem structure and VersionTag-based APIs
Removed the obsolete VersionInfo requirements file
Fixed a Unix-specific shell argument issue in the ProcessRunner test
Removed unused usings that could be flagged by analyzers
Removed the BOM from .github/workflows/build_on_push.yaml

Validation performed during the update work:

dotnet build
targeted dotnet test
dotnet tool restore && dotnet reqstream --requirements requirements.yaml --lint
./lint.sh

- Add '## Configuration File' section to README.md after Usage - Add '# Configuration File' section to docs/user_guide/introduction.md covering connector settings, report sections, and item routing rules - Add BuildMark-Config-* requirements to build-mark.yaml requirements file Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

Malcolmnixon · 2026-04-08T11:01:31Z

@copilot Now please update the design documentation - specifically docs/design/introduction.md and docs/design/build-mark/build-mark.md (the Software Structure, Folder Layout, and System Design. Specifically show the breakdown of System/Subsystem/Unit to handle the configuration file and use it in the tool.

- Update docs/design/introduction.md: - Add Configuration subsystem to Scope section - Add Configuration subsystem (5 units) to Software Structure tree - Add Configuration/ folder and files to Folder Layout - Update docs/design/build-mark/build-mark.md: - Add Configuration row to System Architecture table - Add .buildmark.yaml row to External Interfaces table - Update Data Flow diagram to show BuildMarkConfigReader - Update Self-contained constraint to mention optional config file - Add Configuration File section to Integration Patterns - Create docs/design/build-mark/configuration/configuration.md: - New Configuration subsystem design document - Covers BuildMarkConfig, BuildMarkConfigReader, ConnectorConfig, SectionConfig, and RuleConfig units - Documents interfaces and interactions Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

Copilot · 2026-04-08T11:28:35Z

@copilot Now please update the design documentation - specifically docs/design/introduction.md and docs/design/build-mark/build-mark.md (the Software Structure, Folder Layout, and System Design. Speci...

Done in commit 535ec3d. Three design files were updated:

docs/design/introduction.md — Added Configuration subsystem (5 units: BuildMarkConfig, BuildMarkConfigReader, ConnectorConfig, SectionConfig, RuleConfig) to the Software Structure tree and Folder Layout.
docs/design/build-mark/build-mark.md — Added Configuration to the System Architecture table, .buildmark.yaml to the External Interfaces table, updated the Data Flow diagram to show config loading before connector selection, updated the "Self-contained" constraint, and added a "Configuration File" integration pattern section.
docs/design/build-mark/configuration/configuration.md (new) — Full subsystem design document covering Overview, Units, Interfaces (for all 5 units), and Interactions.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

https://storage.googleapis.com/chromium-browser-snapshots/Linux_x64/1108766/chrome-linux.zip
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node install.js (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

docs/design/build-mark/configuration/configuration.md

docs/design/build-mark/build-mark.md

…figuration design - Fix MD060 table alignment issues in build-mark.md (ItemControls row) and configuration.md (BuildMarkConfig, SectionConfig, ReadAsync rows) - Expand ConnectorConfig interface table with GitHub and AzureDevOps properties - Add GitHubConnectorConfig unit with Owner, Repo, BaseUrl properties - Add AzureDevOpsConnectorConfig placeholder unit (reserved for future use) - Update Interactions section in configuration.md: GitHubRepoConnector reads GitHubConnectorConfig from result.Config.Connector.GitHub - Update repo-connectors.md Interactions: note GitHubConnectorConfig passed from Program via result.Config.Connector.GitHub - Update build-mark.md Configuration File pattern to describe GitHub property carrying GitHubConnectorConfig passed to GitHubRepoConnector - Add new units to Software Structure tree in introduction.md - Add GitHubConnectorConfig.cs and AzureDevOpsConnectorConfig.cs to Folder Layout Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

Malcolmnixon · 2026-04-08T12:24:04Z

@copilot Now let's flow this new configuration stuff down to the other subsystems and units in the design document and requirements for both the new and existing subsystems and units. For example the GitHubRepoConnector should probably take a GitHubConnectorConfig.

Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/18d8f83e-9584-40ef-92c9-fb55c24cd753 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

Copilot · 2026-04-08T13:05:57Z

@copilot Now let's flow this new configuration stuff down to the other subsystems and units in the design document and requirements for both the new and existing subsystems and units. For example the ...

Done in commit 40b8c58. The configuration types are now flowed through all affected units:

Design docs updated:

program.md — Run gets a --lint dispatch step; ProcessBuildNotes calls BuildMarkConfigReader.ReadAsync first and passes result.Config?.Connector to RepoConnectorFactory.Create
repo-connector-factory.md — Create() becomes Create(ConnectorConfig?), documents AzureDevOps type throwing NotSupportedException, and forwards config?.GitHub to GitHubRepoConnector
github-repo-connector.md — GetBuildInformationAsync steps 2 & 4 now describe GitHubConnectorConfig overriding owner/repo and optionally setting the GraphQL base URL; Interactions table updated

Requirements files updated:

program.yaml — new BuildMark-Program-Lint requirement
repo-connector-factory.yaml — new BuildMark-RepoConnectorFactory-ConnectorConfig requirement
github-repo-connector.yaml — new BuildMark-GitHub-ConnectorConfig requirement
build-mark.yaml — system-level config requirements now have children links to subsystem/unit requirements; new BuildMark-Config-Lint system requirement added
requirements.yaml — configuration/configuration.yaml added to includes
configuration/configuration.yaml (new) — full subsystem/unit-level requirements for BuildMarkConfigReader, ConfigurationLoadResult, and GitHubConnectorConfig

- Add BuildNotes subsystem docs (build-notes.md, build-information.md, item-info.md, version.md, version-tag.md, web-link.md) - Move ProcessRunner docs to Utilities subsystem - Add ItemRouter unit doc to RepoConnectors - Add GitHub sub-subsystem docs (github.md, github-repo-connector.md) - Add Mock sub-subsystem docs (mock.md, mock-repo-connector.md) - Update build-mark.md, introduction.md, utilities.md, repo-connectors.md - Update repo-connector-base.md, repo-connector-factory.md, self-test.md, validation.md - Delete old process-runner.md, github-repo-connector.md, mock-repo-connector.md from repo-connectors root Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

…nterval to Utilities Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/10baf5c8-912f-4c4a-ab60-5f7b6188be9f Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

…ies; fix Sub-Subsystem terminology Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/10baf5c8-912f-4c4a-ab60-5f7b6188be9f Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 104 out of 106 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

src/DemaConsulting.BuildMark/Utilities/VersionInterval.cs:66

If LowerBound/UpperBound is non-null but not parseable as a version, Contains currently ignores that bound (effectively treating it as unbounded). That can make invalid intervals match unexpectedly. Consider treating an unparsable bound as a non-match (return false), or validate bounds during Parse so invalid intervals are rejected earlier.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

README.md

docs/user_guide/introduction.md

docs/design/build-mark/configuration/configuration.md

docs/design/build-mark/build-mark.md

test/DemaConsulting.BuildMark.Tests/Utilities/UtilitiesTests.cs

…it (#134) * feat: implement rules/sections routing integration - Add Configure and ApplyRules methods to RepoConnectorBase for centralized routing - Add HasRules protected property to detect when rules are configured - Add RoutedSections property to BuildInformation record - Update ToMarkdown to render custom sections when RoutedSections is set - Update MockRepoConnector to apply routing rules when configured - Update GitHubRepoConnector to apply routing rules when configured - Update Program.cs to call Configure on connectors created from config (not factory) - Add RunRulesRouting self-validation test to Validation.cs - Add unit tests: RepoConnectorBaseTests, extended MockRepoConnectorTests, BuildInformationTests, and GitHubRepoConnectorTests - Update design docs and reqstream yaml files Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> * fix: address code review feedback - Fix TestableRepoConnector.GetBuildInformationAsync to return minimal valid BuildInformation instead of null, preventing potential NullReferenceException - Improve comment on extra sections in ApplyRules to explain the scenario - Add comment explaining tuple discard in AppendRoutedSections loop Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> * Add rules routing docs, requirement, and end-to-end test for GitHubRepoConnector Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/14d76d1d-b9ef-4070-b14f-fa9dd3426801 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> * fix: resolve all lint failures (YAML line-length and markdown table alignment) Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/16b84817-c0a6-4fb9-a425-8242a9745659 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

* Fix all review issues: requirements linkage, README, design docs, test coverage Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/3918c333-4f67-42c8-9a1c-ee892f1a0db6 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> * Fix inverted assertion in BuildInformation ordering test Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/a37c8d0b-2277-4135-bca0-802186087981 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> * Fix review findings: TrimEnd in TryRunAsync, VersionInfo test AAA and property assertions, program.md and validation.md design docs Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/1960a6a1-8eb2-465d-9852-38a659d1eb30 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> * Fix review findings: correct MockRepoConnector hash lookup, ItemControlsParser empty set, ItemRouter tests and docs, RepoConnectorFactory async Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> * Fix ordering assertion: replace IsLessThanOrEqualTo with Assert.IsTrue for unambiguous ascending check Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/36222094-6d73-4faa-b11c-6bb4a2b7af7a Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> * Fix ordering assertion: use IsLessThanOrEqualTo(upperBound, value) with correct argument order Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/64c1829e-933a-47ec-893f-ce8d8483fe38 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> * Update self-validation to expect explicit build version hash Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/b612f886-71a8-4870-b5ef-b22e576547cf Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> * Major project refactoring * Move version units to a new Version subsystem. * Linting cleanups * Improve testing for requirements coverage. * Lint fixes. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> Co-authored-by: Malcolm Nixon <Malcolm.Nixon@hiarc.inc>

Copilot

Pull request overview

Copilot reviewed 144 out of 145 changed files in this pull request and generated 11 comments.

Comments suppressed due to low confidence (5)

src/DemaConsulting.BuildMark/Version/VersionIntervalSet.cs:57

VersionIntervalSet.Contains(VersionTag) currently delegates to version.Numbers, which drops any pre-release information (e.g., 1.0.0-rc.1 becomes 1.0.0). This can yield incorrect containment results for intervals that include pre-release bounds. Delegate to Contains(version.Semantic.Comparable) (or Contains(version.Semantic.CompareVersion)) to preserve SemVer ordering.
src/DemaConsulting.BuildMark/RepoConnectors/ItemControlsParser.cs:24
Unused using DemaConsulting.BuildMark.Utilities; will trigger build failures with analyzers when warnings are treated as errors. Remove the unused using.
docs/design/build-mark/version/version-interval.md:120
This design doc refers to VersionInfo overloads for VersionInterval/VersionIntervalSet, but the code implements overloads for VersionTag instead. Update these method signatures/descriptions to match the current API so the design stays accurate.
docs/reqstream/build-mark/version/version-interval.yaml:39
This requirements doc still references VersionInfo overloads for interval containment, but the implementation uses VersionTag. Update VersionInfo references to VersionTag (and remove the backward-compatibility rationale if VersionInfo no longer exists).
src/DemaConsulting.BuildMark/Version/VersionCommitTag.cs:23
using DemaConsulting.BuildMark.Version; is redundant here (the file is already in namespace DemaConsulting.BuildMark.Version;) and will be flagged as an unnecessary/unused using with code-style analyzers enabled. Remove the using directive.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/DemaConsulting.BuildMark/Version/VersionTag.cs

src/DemaConsulting.BuildMark/RepoConnectors/IRepoConnector.cs

src/DemaConsulting.BuildMark/RepoConnectors/RepoConnectorFactory.cs

README.md

docs/reqstream/build-mark/utilities/version-info.yaml

docs/design/build-mark/utilities/utilities.md

docs/design/build-mark/version/version.md

src/DemaConsulting.BuildMark/Program.cs

.github/workflows/build_on_push.yaml

src/DemaConsulting.BuildMark/Program.cs

Malcolmnixon · 2026-04-09T22:01:14Z

@copilot apply changes based on the comments in this thread

Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/fc411fd4-e97d-4512-980c-3447d83b1554 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

Copilot · 2026-04-09T22:11:06Z

@copilot apply changes based on the comments in this thread

Applied in 5248aa4. I updated the stale config/version docs and requirements to match the current implementation, removed the orphaned VersionInfo requirements file, fixed the Unix shell test arguments, removed the workflow BOM, and re-ran build, targeted tests, lint, and ReqStream validation successfully.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

https://storage.googleapis.com/chromium-browser-snapshots/Linux_x64/1108766/chrome-linux.zip
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node install.js (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Copilot AI and others added 2 commits April 8, 2026 02:37

docs: fix American English spelling in requirements justifications

a26f916

Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

Copilot AI assigned Copilot and Malcolmnixon Apr 8, 2026

Copilot created this pull request from a session on behalf of Malcolmnixon April 8, 2026 09:57 View session

Copilot started work on behalf of Malcolmnixon April 8, 2026 11:01 View session

Copilot finished work on behalf of Malcolmnixon April 8, 2026 11:31

Copilot AI requested a review from Malcolmnixon April 8, 2026 11:31

Malcolmnixon requested changes Apr 8, 2026

View reviewed changes

Copilot started work on behalf of Malcolmnixon April 8, 2026 11:40 View session

Copilot finished work on behalf of Malcolmnixon April 8, 2026 12:20

Copilot AI requested a review from Malcolmnixon April 8, 2026 12:20

Copilot started work on behalf of Malcolmnixon April 8, 2026 12:24 View session

Copilot finished work on behalf of Malcolmnixon April 8, 2026 13:10

Copilot started work on behalf of Malcolmnixon April 8, 2026 13:27 View session

Copilot finished work on behalf of Malcolmnixon April 8, 2026 13:29

Copilot started work on behalf of Malcolmnixon April 8, 2026 13:39 View session

Copilot finished work on behalf of Malcolmnixon April 8, 2026 14:33

Copilot started work on behalf of Malcolmnixon April 8, 2026 14:36 View session

Copilot AI and others added 2 commits April 8, 2026 15:01

Copilot finished work on behalf of Malcolmnixon April 8, 2026 15:33

Copilot AI review requested due to automatic review settings April 8, 2026 21:09

Copilot started reviewing on behalf of Malcolmnixon April 8, 2026 21:10 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

Copilot AI and others added 2 commits April 9, 2026 00:39

Copilot AI review requested due to automatic review settings April 9, 2026 21:11

Copilot started reviewing on behalf of Malcolmnixon April 9, 2026 21:11 View session

Copilot AI reviewed Apr 9, 2026

View reviewed changes

Copilot started work on behalf of Malcolmnixon April 9, 2026 22:01 View session

Apply review thread fixes

5248aa4

Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/fc411fd4-e97d-4512-980c-3447d83b1554 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

Copilot AI changed the title ~~docs: introduce .buildmark.yaml configuration file~~ feat: introduce .buildmark.yaml configuration support and align related documentation Apr 9, 2026

Copilot finished work on behalf of Malcolmnixon April 9, 2026 22:11

Malcolmnixon merged commit 8f37a99 into main Apr 9, 2026
15 checks passed

Malcolmnixon deleted the copilot/add-buildmark-configuration-file branch April 9, 2026 22:28

Conversation

Copilot AI commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request

Description

Type of Change

Related Issues

Pre-Submission Checklist

Build and Test

Code Quality

Quality Checks

Testing

Documentation

Additional Notes

Uh oh!

Malcolmnixon commented Apr 8, 2026

Uh oh!

Copilot AI commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Malcolmnixon commented Apr 8, 2026

Uh oh!

Copilot AI commented Apr 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Malcolmnixon commented Apr 9, 2026

Uh oh!

Copilot AI commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Apr 8, 2026 •

edited

Loading

Copilot AI commented Apr 8, 2026 •

edited

Loading

Copilot AI commented Apr 9, 2026 •

edited

Loading