diff --git a/.github/standards/design-documentation.md b/.github/standards/design-documentation.md index 3b448f32..768bf3f2 100644 --- a/.github/standards/design-documentation.md +++ b/.github/standards/design-documentation.md @@ -35,16 +35,21 @@ design to implementation: ```text docs/design/ -├── introduction.md # Design overview with software structure -└── {system-name}/ # System-level design folder (one per system) - ├── {system-name}.md # System-level design documentation - ├── {subsystem-name}/ # Subsystem (kebab-case); may nest recursively - │ ├── {subsystem-name}.md # Subsystem overview and design - │ ├── {child-subsystem}/ # Child subsystem (same structure as parent) - │ └── {unit-name}.md # Unit-level design documents - └── {unit-name}.md # Top-level unit design documents (if not in subsystem) +├── introduction.md # Document overview - heading depth # +├── {system-name}.md # System-level design - heading depth # +└── {system-name}/ # System folder (one per system) + ├── {subsystem-name}.md # Subsystem overview - heading depth ## + ├── {subsystem-name}/ # Subsystem folder (kebab-case); may nest recursively + │ ├── {child-subsystem}.md # Child subsystem overview - heading depth ### + │ ├── {child-subsystem}/ # Child subsystem folder (same structure as parent) + │ └── {unit-name}.md # Unit design - heading depth ### + └── {unit-name}.md # System-level unit design - heading depth ## ``` +Each scope's overview file lives in its **parent** folder, not inside the scope's own +subfolder - this aligns heading depth with folder depth so the compiled PDF has a +meaningful multi-level outline (see Heading Depth Rule in `technical-documentation.md`). + ## introduction.md (MANDATORY) The `introduction.md` file serves as the design entry point and MUST include @@ -124,23 +129,30 @@ artifact to all related files: Example format: ```text -Each software item in the structure above has corresponding artifacts in -parallel directory trees: - -- Requirements: `docs/reqstream/{system}/.../{item}.yaml` (kebab-case) -- Design docs: `docs/design/{system}/.../{item}.md` (kebab-case) -- Verification design: `docs/verification/{system}/.../{item}.md` (kebab-case) -- Source code: `src/{System}/.../{Item}.{ext}` (cased per language - see `software-items.md`) -- Tests: `test/{System}.Tests/.../{Item}Tests.{ext}` (cased per language - see `software-items.md`) -- Review-sets: defined in `.reviewmark.yaml` +Each in-house software item has corresponding artifacts in parallel directory trees: + +- Requirements: `docs/reqstream/{system-name}.yaml`, `docs/reqstream/{system-name}/.../{item}.yaml` +- Design docs: `docs/design/{system-name}.md`, `docs/design/{system-name}/.../{item}.md` +- Verification: `docs/verification/{system-name}.md`, `docs/verification/{system-name}/.../{item}.md` +- Source code: `src/{SystemName}/.../{Item}.{ext}` (cased per language - see `software-items.md`) +- Tests: `test/{SystemName}.Tests/.../{Item}Tests.{ext}` (cased per language) + +OTS items have no design documentation; their artifacts sit parallel to system folders: + +- Requirements: `docs/reqstream/ots/{ots-name}.yaml` +- Verification: `docs/verification/ots/{ots-name}.md` +- Tests (optional): `test/{OtsSoftwareTests}/...` (cased per language - see `software-items.md`) + +Review-sets: defined in `.reviewmark.yaml` ``` ## System Design Documentation (MANDATORY) For each system identified in the repository: -- Create a kebab-case folder matching the system name -- Include `{system-name}.md` with system-level design documentation such as: +- Create `{system-name}.md` directly under `docs/design/` (heading depth `#`) +- Create a kebab-case folder `{system-name}/` to hold its subsystems and units +- `{system-name}.md` must cover: - System architecture and major components - External interfaces and dependencies - Data flow and control flow @@ -151,16 +163,20 @@ For each system identified in the repository: For each subsystem identified in the software structure: -- Create a kebab-case folder matching the subsystem name (enables automated tooling) -- Include `{subsystem-name}.md` with subsystem overview and design -- Include unit design documents for ALL units within the subsystem +- Place `{subsystem-name}.md` inside the **parent** folder (the system folder, or parent + subsystem folder) - not inside its own subfolder +- Create a kebab-case folder `{subsystem-name}/` to hold its child units and subsystems +- `{subsystem-name}.md` must cover subsystem overview and design For every unit identified in the software structure: +- Place `{unit-name}.md` inside its parent scope's folder (system or subsystem folder) - Document data models, algorithms, and key methods - Describe interactions with other units - Include sufficient detail for formal code review -- Place in appropriate subsystem folder or at design root level + +Follow the Heading Depth Rule from `technical-documentation.md` - a file's top-level +heading depth equals its folder depth under `docs/design/`. # Software Items Integration (CRITICAL) @@ -191,9 +207,11 @@ Before submitting design documentation, verify: - [ ] `introduction.md` includes both Software Structure and Folder Layout sections - [ ] Software structure correctly categorizes items as System/Subsystem/Unit per `software-items.md` - [ ] Folder layout mirrors software structure organization +- [ ] Files organized under `docs/design/` following the folder structure pattern above +- [ ] Each file's top-level heading depth matches its folder depth per the Heading Depth Rule - [ ] Design documents provide sufficient detail for code review - [ ] System documentation provides comprehensive system-level design -- [ ] Subsystem documentation folders use kebab-case names while mirroring source subsystem names and structure +- [ ] All documentation folders use kebab-case names mirroring source code structure - [ ] All documents follow technical documentation formatting standards - [ ] Content is current with implementation and requirements - [ ] Documents are integrated into ReviewMark review-sets for formal review diff --git a/.github/standards/reqstream-usage.md b/.github/standards/reqstream-usage.md index 58b08b4d..303bb43f 100644 --- a/.github/standards/reqstream-usage.md +++ b/.github/standards/reqstream-usage.md @@ -18,20 +18,25 @@ because ReqStream discovers files via the includes chain in `requirements.yaml` and organizes report output by this hierarchy: ```text -requirements.yaml # Root file (includes only) +requirements.yaml # Root file (includes only) docs/reqstream/ -├── {system-name}/ # System-level requirements folder (one per system) -│ ├── {system-name}.yaml # System-level requirements +├── {system-name}.yaml # System-level requirements +├── {system-name}/ # System folder (one per system) │ ├── platform-requirements.yaml # Platform support requirements -│ ├── {subsystem-name}/ # Subsystem (kebab-case); may nest recursively -│ │ ├── {subsystem-name}.yaml # Requirements for this subsystem -│ │ ├── {child-subsystem}/ # Child subsystem (same structure as parent) -│ │ └── {unit-name}.yaml # Requirements for units within this subsystem -│ └── {unit-name}.yaml # Requirements for top-level units (outside subsystems) -└── ots/ # OTS items appear as a distinct section in reports - └── {ots-name}.yaml # Requirements for OTS components +│ ├── {subsystem-name}.yaml # Subsystem requirements +│ ├── {subsystem-name}/ # Subsystem folder (kebab-case); may nest recursively +│ │ ├── {child-subsystem}.yaml # Child subsystem requirements +│ │ ├── {child-subsystem}/ # Child subsystem folder +│ │ └── {unit-name}.yaml # Unit requirements +│ └── {unit-name}.yaml # System-level unit requirements +└── ots/ # OTS items appear as a distinct section in reports + └── {ots-name}.yaml # Requirements for OTS components ``` +In-house items have matching relative paths across `docs/reqstream/`, `docs/design/`, and +`docs/verification/`. OTS items appear only in `docs/reqstream/ots/` and +`docs/verification/ots/` - they have no design documentation. + # Requirements File Format ```yaml @@ -62,7 +67,7 @@ sections: sections: - title: System.Text.Json requirements: - - id: TemplateTool-SystemTextJson-ReadJson + - id: SystemTextJson-Core-ReadJson title: System.Text.Json shall be able to read JSON files. tests: - JsonReaderTests.TestReadValidJson @@ -124,8 +129,8 @@ Before submitting requirements, verify: - [ ] Every requirement links to at least one passing test - [ ] Platform-specific requirements use source filters (`platform@TestName`) - [ ] Comprehensive justification explains business/regulatory need -- [ ] Files organized under `docs/reqstream/` following folder structure patterns -- [ ] Subsystem folders use kebab-case naming matching source code +- [ ] Files organized under `docs/reqstream/` following the folder structure pattern above +- [ ] All documentation folders use kebab-case names matching source code structure - [ ] OTS requirements placed in `ots/` subfolder - [ ] Valid YAML syntax passes yamllint validation - [ ] Test result formats compatible (TRX, JUnit XML) diff --git a/.github/standards/reviewmark-usage.md b/.github/standards/reviewmark-usage.md index 2f778dcd..2d958320 100644 --- a/.github/standards/reviewmark-usage.md +++ b/.github/standards/reviewmark-usage.md @@ -61,6 +61,17 @@ needs-review: # Source of review evidence evidence-source: type: none + +# Review-sets (each focuses on a single compliance question) +reviews: + - id: Purpose + title: Review of user-facing capabilities and system promises + paths: + - "README.md" + - "docs/user_guide/**/*.md" + - "docs/reqstream/{system-name}.yaml" + - "docs/design/introduction.md" + - "docs/design/{system-name}.md" ``` # Review-Set Design Principles @@ -95,9 +106,9 @@ Reviews user-facing capabilities and system promises: - **File Path Patterns**: - README: `README.md` - User guide: `docs/user_guide/**/*.md` - - System requirements: `docs/reqstream/{system-name}/{system-name}.yaml` + - System requirements: `docs/reqstream/{system-name}.yaml` - Design introduction: `docs/design/introduction.md` - - System design: `docs/design/{system-name}/{system-name}.md` + - System design: `docs/design/{system-name}.md` ## `{System}-Architecture` Review (one per system) @@ -108,11 +119,11 @@ Reviews system architecture and operational validation: - **Scope**: Excludes subsystem and unit files, relying on system-level design to describe what subsystems and units it uses - **File Path Patterns**: - - System requirements: `docs/reqstream/{system-name}/{system-name}.yaml` + - System requirements: `docs/reqstream/{system-name}.yaml` - Design introduction: `docs/design/introduction.md` - - System design: `docs/design/{system-name}/{system-name}.md` + - System design: `docs/design/{system-name}.md` - Verification introduction: `docs/verification/introduction.md` - - System verification design: `docs/verification/{system-name}/{system-name}.md` + - System verification design: `docs/verification/{system-name}.md` - System integration tests: `test/{SystemName}.Tests/{SystemName}Tests.{ext}` ## `{System}-Design` Review (one per system) @@ -123,9 +134,10 @@ Reviews architectural and design consistency: - **Title**: "Review that {System} Design is Consistent and Complete" - **Scope**: Only brings in top-level requirements and relies on brevity of design documentation - **File Path Patterns**: - - System requirements: `docs/reqstream/{system-name}/{system-name}.yaml` + - System requirements: `docs/reqstream/{system-name}.yaml` - Platform requirements: `docs/reqstream/{system-name}/platform-requirements.yaml` - Design introduction: `docs/design/introduction.md` + - System design: `docs/design/{system-name}.md` - System design files: `docs/design/{system-name}/**/*.md` ## `{System}-AllRequirements` Review (one per system) @@ -137,8 +149,8 @@ Reviews requirements quality and traceability: - **Scope**: Only brings in requirements files to keep review manageable - **File Path Patterns**: - Root requirements: `requirements.yaml` - - System requirements: `docs/reqstream/{system-name}/**/*.yaml` - - OTS requirements: `docs/reqstream/ots/**/*.yaml` (if applicable) + - System requirements: `docs/reqstream/{system-name}.yaml` + - Subsystem/unit requirements: `docs/reqstream/{system-name}/**/*.yaml` ## `{System}-{Subsystem[-Child...]}` Review (one per subsystem at any depth) @@ -149,9 +161,9 @@ Reviews subsystem architecture and interfaces: - **Scope**: Excludes units under the subsystem, relying on subsystem design to describe what units it uses - **File Path Patterns**: - - Requirements: `docs/reqstream/{system-name}/.../{subsystem-name}/{subsystem-name}.yaml` - - Design: `docs/design/{system-name}/.../{subsystem-name}/{subsystem-name}.md` - - Verification design: `docs/verification/{system-name}/.../{subsystem-name}/{subsystem-name}.md` + - Requirements: `docs/reqstream/{system-name}/.../{subsystem-name}.yaml` + - Design: `docs/design/{system-name}/.../{subsystem-name}.md` + - Verification design: `docs/verification/{system-name}/.../{subsystem-name}.md` - Tests: `test/{SystemName}.Tests/.../{SubsystemName}/{SubsystemName}Tests.{ext}` ## `{System}-{Subsystem[-Child...]}-{Unit}` Review (one per unit) @@ -168,6 +180,19 @@ Reviews individual software unit implementation: - Source: `src/{SystemName}/.../{UnitName}.{ext}` - Tests: `test/{SystemName}.Tests/.../{UnitName}Tests.{ext}` +## `OTS-{OtsName}` Review (one per OTS item) + +Reviews OTS item requirements and verification evidence: + +- **Purpose**: Proves that the OTS item provides the required functionality +- **Title**: "Review that {OtsName} Provides Required Functionality" +- **Scope**: OTS items have no in-house design or source; review covers requirements and + verification evidence only +- **File Path Patterns**: + - OTS requirements: `docs/reqstream/ots/{ots-name}.yaml` + - OTS verification: `docs/verification/ots/{ots-name}.md` + - Tests (if applicable): `test/{OtsSoftwareTests}/...` (cased per language) + **Note**: File path patterns use `{ext}` as a placeholder for language-specific extensions (`.cs`, `.cpp`/`.hpp`, `.py`, etc.). Adapt to your repository's languages. @@ -184,6 +209,7 @@ Before submitting ReviewMark configuration, verify: - [ ] Architecture review-sets include system verification design alongside system design - [ ] Subsystem review-sets include subsystem verification design - [ ] Unit review-sets include unit verification design +- [ ] OTS review-sets include OTS requirements and verification evidence - [ ] Each review-set focuses on a single compliance question (single focus principle) - [ ] File patterns use correct glob syntax and match intended files - [ ] Review-set file counts remain manageable (context management principle) diff --git a/.github/standards/software-items.md b/.github/standards/software-items.md index 4e5c90e5..6be029f9 100644 --- a/.github/standards/software-items.md +++ b/.github/standards/software-items.md @@ -81,6 +81,14 @@ Choose the appropriate category based on scope and testability: consumes it - Tested through integration tests proving required functionality works - Examples: System.Text.Json, Entity Framework, third-party APIs +- **Artifact locations** (OTS items have no design documentation): + - Requirements: `docs/reqstream/ots/{ots-name}.yaml` + - Verification: `docs/verification/ots/{ots-name}.md` + - These folders sit parallel to system folders (not inside any system folder) +- System design documentation records which OTS items each system depends on +- **OTS test project**: If no other verification evidence is available (e.g., vendor test results, + published compliance reports), a dedicated test project (`OtsSoftwareTests` / `ots_software_tests`, + cased per language) holds OTS integration tests - one test file per OTS item requiring tests. # Software Item Artifact Model diff --git a/.github/standards/technical-documentation.md b/.github/standards/technical-documentation.md index 7ff5b5ad..2ac29f47 100644 --- a/.github/standards/technical-documentation.md +++ b/.github/standards/technical-documentation.md @@ -84,6 +84,23 @@ elsewhere causes duplicate sections in the compiled PDF. List documents in logical reading order in Pandoc configuration because readers need coherent information flow from general to specific topics. +## Heading Depth Rule (MANDATORY) + +A file's top-level heading depth must equal its folder depth under the document +collection root - this ensures Pandoc can concatenate all files in `definition.yaml` +order and produce a coherent outline with no heading-shift configuration: + +| Folder depth | Top heading | +| --- | --- | +| 0 - collection root | `#` | +| 1 - one subfolder deep | `##` | +| 2 - two subfolders deep | `###` | +| N - N subfolders deep | `#` × (N+1) | + +Internal sections use the next heading level down (e.g. a `##` file uses `###` +for *Overview*, *Interfaces*, etc.). Deeply nested files have fewer heading levels +available - keep internal structure flat to avoid excessive nesting. + # Writing Guidelines Write technical documentation for clarity and compliance verification: diff --git a/.github/standards/verification-documentation.md b/.github/standards/verification-documentation.md index f6f407fd..8eea3b70 100644 --- a/.github/standards/verification-documentation.md +++ b/.github/standards/verification-documentation.md @@ -23,18 +23,25 @@ Organize under `docs/verification/` mirroring the software item hierarchy: ```text docs/verification/ -├── introduction.md # Verification overview -├── {system-name}/ # System-level verification folder (one per system) -│ ├── {system-name}.md # System-level verification design -│ ├── {subsystem-name}/ # Subsystem (kebab-case); may nest recursively -│ │ ├── {subsystem-name}.md # Subsystem verification design -│ │ ├── {child-subsystem}/ # Child subsystem (same structure as parent) -│ │ └── {unit-name}.md # Unit-level verification design documents -│ └── {unit-name}.md # Top-level unit verification documents (if not in subsystem) -└── ots/ # OTS items (one verification file per OTS item) - └── {ots-name}.md # Verification evidence for each OTS item +├── introduction.md # Document overview - heading depth # +├── {system-name}.md # System-level verification - heading depth # +├── {system-name}/ # System folder (one per system) +│ ├── {subsystem-name}.md # Subsystem verification - heading depth ## +│ ├── {subsystem-name}/ # Subsystem folder (kebab-case); may nest recursively +│ │ ├── {child-subsystem}.md # Child subsystem verification - heading depth ### +│ │ ├── {child-subsystem}/ # Child subsystem folder (same structure as parent) +│ │ └── {unit-name}.md # Unit verification - heading depth ### +│ └── {unit-name}.md # System-level unit verification - heading depth ## +├── ots.md # OTS section overview - heading depth # (MANDATORY if OTS items exist) +└── ots/ # OTS items - parallel to system folders (not inside them) + └── {ots-name}.md # OTS item verification evidence - heading depth ## ``` +Each scope's overview file lives in its **parent** folder, not inside the scope's own +subfolder - this keeps artifact locations consistent with design and requirements trees +so any item's files are deterministically locatable, and aligns heading depth with folder +depth for correct PDF structure (see Heading Depth Rule in `technical-documentation.md`). + ## introduction.md (MANDATORY) Follow the standard `introduction.md` format from `technical-documentation.md`. Scope @@ -45,16 +52,16 @@ artifact to all related files: ```text In-house items have parallel artifacts in: -- Requirements: `docs/reqstream/{system}/.../{item}.yaml` (kebab-case) -- Design: `docs/design/{system}/.../{item}.md` (kebab-case) -- Verification: `docs/verification/{system}/.../{item}.md` (kebab-case) -- Source: `src/{System}/.../{Item}.{ext}` (cased per language) -- Tests: `test/{System}.Tests/.../{Item}Tests.{ext}` (cased per language) +- Requirements: `docs/reqstream/{system-name}.yaml`, `docs/reqstream/{system-name}/.../{item}.yaml` +- Design: `docs/design/{system-name}.md`, `docs/design/{system-name}/.../{item}.md` +- Verification: `docs/verification/{system-name}.md`, `docs/verification/{system-name}/.../{item}.md` +- Source: `src/{SystemName}/.../{Item}.{ext}` (cased per language) +- Tests: `test/{SystemName}.Tests/.../{Item}Tests.{ext}` (cased per language) -OTS items have parallel artifacts in: -- Requirements: `docs/reqstream/ots/{ots-name}.yaml` (kebab-case) -- Verification: `docs/verification/ots/{ots-name}.md` (kebab-case) -- Tests: `test/{OtsName}.Tests/...` (cased per language, if required) +OTS items (no design documentation) have artifacts parallel to system folders: +- Requirements: `docs/reqstream/ots/{ots-name}.yaml` +- Verification: `docs/verification/ots/{ots-name}.md` +- Tests (if required): `test/{OtsSoftwareTests}/...` (cased per language - see `software-items.md`) Review-sets: defined in `.reviewmark.yaml` ``` @@ -64,7 +71,8 @@ a `## References` section in `introduction.md` only - do not add one to any othe ## System Verification Design (MANDATORY) -For each system, create a kebab-case folder and `{system-name}.md` covering: +For each system, create `{system-name}.md` at `docs/verification/` root and a +`{system-name}/` folder for subsystems. Cover: - System verification strategy and overall test approach - Test environments and configuration required @@ -75,7 +83,8 @@ For each system, create a kebab-case folder and `{system-name}.md` covering: ## Subsystem Verification Design (MANDATORY) -For each subsystem, create a kebab-case folder and `{subsystem-name}.md` covering: +For each subsystem, place `{subsystem-name}.md` in the parent (system or subsystem) +folder and create a `{subsystem-name}/` folder for its units. Cover: - Subsystem verification strategy and integration test approach - Dependencies that must be mocked or stubbed at the subsystem boundary @@ -84,7 +93,7 @@ For each subsystem, create a kebab-case folder and `{subsystem-name}.md` coverin ## Unit Verification Design (MANDATORY) -For each unit, create `{unit-name}.md` covering: +Place `{unit-name}.md` in the parent (system or subsystem) folder. Cover: - Verification approach for each unit requirement - Named test scenarios including boundary conditions, error paths, and normal-operation cases @@ -93,6 +102,10 @@ For each unit, create `{unit-name}.md` covering: ## OTS Verification Evidence (when OTS items are used) +Create `docs/verification/ots.md` at the collection root with a `#` top-level heading. This +file introduces the OTS verification approach and ensures OTS items compile as a top-level +section in the PDF rather than as subsystems of the last in-house system. + For each OTS item, create `docs/verification/ots/{ots-name}.md` covering: - The OTS item's required functionality (reference `docs/reqstream/ots/{ots-name}.yaml`) @@ -121,8 +134,11 @@ Before submitting verification documentation, verify: - [ ] System verification documents cover end-to-end and integration scenarios - [ ] Subsystem verification documents identify mocked boundaries and integration scenarios - [ ] Unit verification documents identify individual scenarios including boundary and error paths -- [ ] Subsystem documentation folders use kebab-case names mirroring the source subsystem structure +- [ ] Files organized under `docs/verification/` following the folder structure pattern above +- [ ] Each file's top-level heading depth matches its folder depth per the Heading Depth Rule +- [ ] All documentation folders use kebab-case names mirroring source code structure - [ ] All documents follow technical documentation formatting standards - [ ] Content is current with requirements and test implementation - [ ] Every OTS item has `docs/verification/ots/{ots-name}.md` with requirement coverage +- [ ] `docs/verification/ots.md` exists with a `#` heading when OTS items are present - [ ] Documents are integrated into ReviewMark review-sets for formal review diff --git a/.reviewmark.yaml b/.reviewmark.yaml index a17a717e..602b2ae7 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -59,6 +59,7 @@ reviews: - "docs/design/introduction.md" - "docs/design/build-mark/**/*.md" - "docs/verification/introduction.md" + - "docs/verification/ots.md" - id: BuildMark-AllRequirements title: Review of All BuildMark requirements quality and traceability @@ -269,7 +270,7 @@ reviews: - "docs/verification/build-mark/configuration/build-mark-config.md" - "docs/verification/build-mark/configuration/connector-config.md" - "docs/verification/build-mark/configuration/git-hub-connector-config.md" - - "docs/verification/build-mark/configuration/azure-dev-ops-connector-config.md" + - "docs/verification/build-mark/configuration/azure-devops-connector-config.md" - "docs/verification/build-mark/configuration/report-config.md" - "docs/verification/build-mark/configuration/section-config.md" - "docs/verification/build-mark/configuration/rule-config.md" @@ -338,8 +339,8 @@ reviews: title: Review that BuildMark RepoConnectors Mock Satisfies Sub-Subsystem Requirements paths: - "docs/reqstream/build-mark/repo-connectors/mock/mock.yaml" - - "docs/design/build-mark/repo-connectors/mock/mock.md" - - "docs/verification/build-mark/repo-connectors/mock/mock.md" + - "docs/design/build-mark/repo-connectors/mock.md" + - "docs/verification/build-mark/repo-connectors/mock.md" - "test/**/RepoConnectors/Mock/MockTests.cs" - id: BuildMark-RepoConnectors-Mock-MockRepoConnector @@ -355,8 +356,8 @@ reviews: title: Review that BuildMark RepoConnectors GitHub Satisfies Sub-Subsystem Requirements paths: - "docs/reqstream/build-mark/repo-connectors/github/github.yaml" - - "docs/design/build-mark/repo-connectors/github/github.md" - - "docs/verification/build-mark/repo-connectors/github/github.md" + - "docs/design/build-mark/repo-connectors/github.md" + - "docs/verification/build-mark/repo-connectors/github.md" - "test/**/RepoConnectors/GitHub/GitHubTests.cs" - id: BuildMark-RepoConnectors-GitHub-GitHubGraphQLClient @@ -392,8 +393,8 @@ reviews: title: Review that BuildMark RepoConnectors AzureDevOps Satisfies Sub-Subsystem Requirements paths: - "docs/reqstream/build-mark/repo-connectors/azure-devops/azure-devops.yaml" - - "docs/design/build-mark/repo-connectors/azure-devops/azure-devops.md" - - "docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops.md" + - "docs/design/build-mark/repo-connectors/azure-devops.md" + - "docs/verification/build-mark/repo-connectors/azure-devops.md" - "test/**/RepoConnectors/AzureDevOps/AzureDevOpsTests.cs" - id: BuildMark-RepoConnectors-AzureDevOps-AzureDevOpsRestClient @@ -402,8 +403,8 @@ reviews: - "docs/reqstream/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.yaml" - "docs/design/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md" - "docs/design/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md" - - "docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops-rest-client.md" - - "docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops-api-types.md" + - "docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md" + - "docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md" - "src/**/RepoConnectors/AzureDevOps/AzureDevOpsRestClient.cs" - "src/**/RepoConnectors/AzureDevOps/AzureDevOpsApiTypes.cs" - "test/**/RepoConnectors/AzureDevOps/MockAzureDevOpsHttpMessageHandler.cs" @@ -414,7 +415,7 @@ reviews: paths: - "docs/reqstream/build-mark/repo-connectors/azure-devops/work-item-mapper.yaml" - "docs/design/build-mark/repo-connectors/azure-devops/work-item-mapper.md" - - "docs/verification/build-mark/repo-connectors/azure-dev-ops/work-item-mapper.md" + - "docs/verification/build-mark/repo-connectors/azure-devops/work-item-mapper.md" - "src/**/RepoConnectors/AzureDevOps/WorkItemMapper.cs" - "test/**/RepoConnectors/AzureDevOps/WorkItemMapperTests.cs" @@ -423,7 +424,7 @@ reviews: paths: - "docs/reqstream/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.yaml" - "docs/design/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md" - - "docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops-repo-connector.md" + - "docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md" - "src/**/RepoConnectors/AzureDevOps/AzureDevOpsRepoConnector.cs" - "test/**/RepoConnectors/AzureDevOps/AzureDevOpsRepoConnectorTests.cs" - "test/**/RepoConnectors/AzureDevOps/MockableAzureDevOpsRepoConnector.cs" diff --git a/docs/design/build-mark/build-mark.md b/docs/design/build-mark.md similarity index 100% rename from docs/design/build-mark/build-mark.md rename to docs/design/build-mark.md diff --git a/docs/design/build-mark/build-notes/build-notes.md b/docs/design/build-mark/build-notes.md similarity index 95% rename from docs/design/build-mark/build-notes/build-notes.md rename to docs/design/build-mark/build-notes.md index 39177153..84c03957 100644 --- a/docs/design/build-mark/build-notes/build-notes.md +++ b/docs/design/build-mark/build-notes.md @@ -1,6 +1,6 @@ -# BuildNotes Subsystem +## BuildNotes Subsystem -## Overview +### Overview The BuildNotes subsystem holds the output data model shared by all connectors and by `Program`. It defines the records that represent a build's version tags, @@ -10,7 +10,7 @@ a markdown report. All connectors produce a `BuildInformation` record from these types, and `Program` calls `BuildInformation.ToMarkdown` to write the final report file. -## Units +### Units | Unit | File | Responsibility | |--------------------|----------------------------------|--------------------------------------------------| @@ -18,7 +18,7 @@ calls `BuildInformation.ToMarkdown` to write the final report file. | `ItemInfo` | `BuildNotes/ItemInfo.cs` | Single issue or pull request in the report | | `WebLink` | `BuildNotes/WebLink.cs` | Hyperlink used for the full-changelog entry | -## Interactions +### Interactions | Unit / Subsystem | Role | |---------------------|--------------------------------------------------------------------| diff --git a/docs/design/build-mark/build-notes/build-information.md b/docs/design/build-mark/build-notes/build-information.md index ef71b0f9..512e5eb5 100644 --- a/docs/design/build-mark/build-notes/build-information.md +++ b/docs/design/build-mark/build-notes/build-information.md @@ -1,12 +1,12 @@ -# BuildInformation +### BuildInformation -## Overview +#### Overview `BuildInformation` is a record in the BuildNotes subsystem that holds all data needed to produce one markdown build-notes report. It is assembled by connectors and passed to `Program`, which calls `ToMarkdown` to render the final file. -## Data Model +#### Data Model ```csharp public record BuildInformation( @@ -30,9 +30,9 @@ public record BuildInformation( optional ordered list of custom report sections populated by `RepoConnectorBase.ApplyRules` when routing rules are configured; `null` when no rules are active -## Methods +#### Methods -### `ToMarkdown(headingDepth, includeKnownIssues) → string` +##### `ToMarkdown(headingDepth, includeKnownIssues) → string` Renders the build information as a markdown string. The `headingDepth` parameter controls the top-level heading depth (default `1`), allowing the report to be @@ -57,7 +57,7 @@ The rendered output contains the following sections: 3. **Full Changelog** *(optional)* - hyperlink from `CompleteChangelogLink`, emitted only when the link is non-null. -## Interactions +#### Interactions | Unit / Subsystem | Role | | :----------------- | :---------------------------------------------------------------- | diff --git a/docs/design/build-mark/build-notes/item-info.md b/docs/design/build-mark/build-notes/item-info.md index ef554231..16cc055d 100644 --- a/docs/design/build-mark/build-notes/item-info.md +++ b/docs/design/build-mark/build-notes/item-info.md @@ -1,12 +1,12 @@ -# ItemInfo +### ItemInfo -## Overview +#### Overview `ItemInfo` is a record in the BuildNotes subsystem that represents a single issue or pull request entry in the build report. It is produced by connectors and stored in the `Changes`, `Bugs`, and `KnownIssues` lists of `BuildInformation`. -## Data Model +#### Data Model ```csharp public record ItemInfo( @@ -27,7 +27,7 @@ public record ItemInfo( | `Index` | `int` | Numeric issue/PR number for deterministic sorting | | `AffectedVersions` | `VersionIntervalSet?` | Interval set from the `affected-versions` field, or `null` | -## Interactions +#### Interactions | Unit / Subsystem | Role | |---------------------|-------------------------------------------------------------| diff --git a/docs/design/build-mark/build-notes/web-link.md b/docs/design/build-mark/build-notes/web-link.md index 09d5515e..eaa948b1 100644 --- a/docs/design/build-mark/build-notes/web-link.md +++ b/docs/design/build-mark/build-notes/web-link.md @@ -1,12 +1,12 @@ -# WebLink +### WebLink -## Overview +#### Overview `WebLink` is a record in the BuildNotes subsystem that represents a hyperlink. It is used by `BuildInformation` to carry the optional complete-changelog link that appears at the end of the rendered markdown report. -## Data Model +#### Data Model ```csharp public record WebLink( @@ -17,7 +17,7 @@ public record WebLink( - `LinkText` (`string`) is the human-readable link label shown in the report. - `TargetUrl` (`string`) is the fully-qualified URL that the link points to. -## Interactions +#### Interactions - `BuildInformation` holds a `WebLink?` as `CompleteChangelogLink`. - `RepoConnectors` construct the `WebLink` from baseline and current tags. diff --git a/docs/design/build-mark/cli/cli.md b/docs/design/build-mark/cli.md similarity index 97% rename from docs/design/build-mark/cli/cli.md rename to docs/design/build-mark/cli.md index 20d7968c..993b99c8 100644 --- a/docs/design/build-mark/cli/cli.md +++ b/docs/design/build-mark/cli.md @@ -1,6 +1,6 @@ -# Cli Subsystem +## Cli Subsystem -## Overview +### 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, @@ -9,13 +9,13 @@ 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 +### Units | Unit | File | Responsibility | |-----------|------------------|---------------------------------------------| | `Context` | `Cli/Context.cs` | Argument parsing, output routing, exit code | -## Interfaces +### Interfaces `Context` exposes the following outward-facing interface consumed by `Program`: @@ -40,7 +40,7 @@ subsystems receive a `Context` from the caller rather than creating one themselv > `Create(args)` throws `ArgumentException` for invalid or malformed arguments. -## Interactions +### 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/build-mark/cli/context.md b/docs/design/build-mark/cli/context.md index 86695f4b..2778724e 100644 --- a/docs/design/build-mark/cli/context.md +++ b/docs/design/build-mark/cli/context.md @@ -1,6 +1,6 @@ -# Context +### Context -## Overview +#### 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. @@ -10,9 +10,9 @@ 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 +#### Data Model -### Parsed Flags +##### Parsed Flags | Property | Type | Default | Source | |----------------------|--------|---------|--------------------------| @@ -23,7 +23,7 @@ so that any open log file is properly flushed and closed. | `Lint` | `bool` | `false` | `--lint` | | `IncludeKnownIssues` | `bool` | `false` | `--include-known-issues` | -### Parsed Arguments +##### Parsed Arguments | Property | Type | Default | Source | |--------------------|-------------------------|---------|----------------------------------------| @@ -33,48 +33,48 @@ so that any open log file is properly flushed and closed. | `ResultsFile` | `string?` | `null` | `--result ` / `--results ` | | `ConnectorFactory` | `Func?` | `null` | Injected via overload | -### Derived State +##### Derived State | Property | Type | Description | |------------|-------|---------------------------------------------------| | `ExitCode` | `int` | `0` if no errors have been written; `1` otherwise | -## Methods +#### Methods -### `Create(string[] args) → Context` +##### `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` +##### `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)` +##### `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)` +##### `WriteLine(string message)` Writes `message` to standard output (unless `Silent` is set) and to the log file (if open). -### `WriteError(string message)` +##### `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()` +##### `Dispose()` Flushes and closes the log file stream. Safe to call multiple times. -## Inner Class: `ArgumentParser` +#### Inner Class: `ArgumentParser` `ArgumentParser` is a private nested class used exclusively by `Create`. It iterates over the argument array and classifies each token: diff --git a/docs/design/build-mark/configuration/configuration.md b/docs/design/build-mark/configuration.md similarity index 99% rename from docs/design/build-mark/configuration/configuration.md rename to docs/design/build-mark/configuration.md index 10b4a7a0..8489b712 100644 --- a/docs/design/build-mark/configuration/configuration.md +++ b/docs/design/build-mark/configuration.md @@ -1,6 +1,6 @@ -# Configuration Subsystem +## Configuration Subsystem -## Overview +### Overview The Configuration subsystem is responsible for reading and parsing the optional `.buildmark.yaml` file located in the repository root. It uses the YamlDotNet @@ -16,7 +16,7 @@ the file is present but malformed, the result carries `null` for the configuration alongside a list of `ConfigurationIssue` records describing each problem with its file path, line number, severity, and description. -## Units +### Units | Unit | File | Responsibility | |-----------------------------|-----------------------------------------------|----------------------------------------| @@ -32,7 +32,7 @@ problem with its file path, line number, severity, and description. | `RuleConfig` | `Configuration/RuleConfig.cs` | Item routing rule data model | | `RuleMatchConfig` | `Configuration/RuleConfig.cs` | Conditions for an item routing rule | -## Interfaces +### Interfaces `BuildMarkConfigReader` exposes the following outward-facing interface consumed by `Program`: @@ -129,7 +129,7 @@ problem with its file path, line number, severity, and description. | `Label` | Property | List of label values; the rule matches when any label is present | | `WorkItemType` | Property | List of work-item type values; rule matches when any type matches | -## Interactions +### Interactions | Unit / Subsystem | Role | |----------------------------|-------------------------------------------------------------------------------| diff --git a/docs/design/build-mark/configuration/build-mark-config-reader.md b/docs/design/build-mark/configuration/build-mark-config-reader.md index 718d56e3..4b75fe11 100644 --- a/docs/design/build-mark/configuration/build-mark-config-reader.md +++ b/docs/design/build-mark/configuration/build-mark-config-reader.md @@ -1,6 +1,6 @@ -# BuildMarkConfigReader +### BuildMarkConfigReader -## Overview +#### Overview `BuildMarkConfigReader` is a static utility class responsible for reading and deserializing the optional `.buildmark.yaml` file from the repository root. It uses the YamlDotNet library's @@ -10,13 +10,13 @@ to produce a strongly-typed `BuildMarkConfig` object. The method always returns a `ConfigurationLoadResult` and never throws. Parse errors and validation warnings are captured as `ConfigurationIssue` records within the result. -## Interface +#### Interface | Member | Kind | Description | |-------------------|---------------|---------------------------------------------------------------------------| | `ReadAsync(path)` | Static method | Reads and deserializes `.buildmark.yaml`; always returns a load result | -### `ReadAsync(string path) → Task` +##### `ReadAsync(string path) → Task` Looks for a `.buildmark.yaml` file at the supplied path (normally the repository root): @@ -26,7 +26,7 @@ Looks for a `.buildmark.yaml` file at the supplied path (normally the repository - If the file is valid, returns a result with a fully populated `BuildMarkConfig` and an empty issues list. -## Interactions +#### Interactions | Unit / Subsystem | Role | |---------------------------|----------------------------------------------------------------------------| diff --git a/docs/design/build-mark/configuration/build-mark-config.md b/docs/design/build-mark/configuration/build-mark-config.md index 63c78454..22f5cf9e 100644 --- a/docs/design/build-mark/configuration/build-mark-config.md +++ b/docs/design/build-mark/configuration/build-mark-config.md @@ -1,6 +1,6 @@ -# BuildMarkConfig +### BuildMarkConfig -## Overview +#### Overview `BuildMarkConfig` is the top-level configuration data model for BuildMark. It holds all settings read from the `.buildmark.yaml` file, including connector configuration, report @@ -9,7 +9,7 @@ settings, section definitions, and item routing rules. When no `.buildmark.yaml` file is present, `Program` calls `BuildMarkConfig.CreateDefault()` to obtain a default configuration with built-in section and rule definitions. -## Data Model +#### Data Model | Property | Type | Description | |-------------|--------------------------|-------------------------------------------------------| @@ -18,7 +18,7 @@ to obtain a default configuration with built-in section and rule definitions. | `Sections` | `IList` | Ordered list of report section definitions | | `Rules` | `IList` | List of item routing rules | -## Interactions +#### Interactions | Unit / Subsystem | Role | |--------------------------|----------------------------------------------------------------------------------| diff --git a/docs/design/build-mark/configuration/configuration-issue.md b/docs/design/build-mark/configuration/configuration-issue.md index 7b98c9fb..caf93347 100644 --- a/docs/design/build-mark/configuration/configuration-issue.md +++ b/docs/design/build-mark/configuration/configuration-issue.md @@ -1,12 +1,12 @@ -# ConfigurationIssue +### ConfigurationIssue -## Overview +#### Overview `ConfigurationIssue` is an immutable record representing a single problem found while reading or validating the `.buildmark.yaml` file. Each issue carries a file path, line number, severity, and human-readable description. -## Data Model +#### Data Model | Property | Type | Description | |---------------|-----------------------------|----------------------------------------------------| @@ -22,7 +22,7 @@ severity, and human-readable description. | `Warning` | Non-fatal issue; tool continues and exit code is 0 | | `Error` | Fatal issue; tool reports all errors, exits with code 1 | -## Interactions +#### Interactions | Unit / Subsystem | Role | |---------------------------|----------------------------------------------------------------| diff --git a/docs/design/build-mark/configuration/configuration-load-result.md b/docs/design/build-mark/configuration/configuration-load-result.md index 1501edfc..942fcd66 100644 --- a/docs/design/build-mark/configuration/configuration-load-result.md +++ b/docs/design/build-mark/configuration/configuration-load-result.md @@ -1,6 +1,6 @@ -# ConfigurationLoadResult +### ConfigurationLoadResult -## Overview +#### Overview `ConfigurationLoadResult` is an immutable record that carries the output of `BuildMarkConfigReader.ReadAsync`. It holds the parsed configuration (or `null` if parsing @@ -9,7 +9,7 @@ failed) together with an ordered list of issues found during parsing. `Program` calls `result.ReportTo(context)` immediately after reading the configuration to surface any issues to the user and set the exit code when errors are present. -## Data Model +#### Data Model | Member | Kind | Description | |---------------------|----------|----------------------------------------------------------| @@ -18,12 +18,12 @@ surface any issues to the user and set the exit code when errors are present. | `HasErrors` | Property | `true` when any issue has `Severity` of `Error` | | `ReportTo(context)` | Method | Writes all issues to `Context`; sets exit code on errors | -### `ReportTo(Context context)` +##### `ReportTo(Context context)` Iterates `Issues` and writes each one to the context output. If any issue has severity `Error`, sets `context.ExitCode` to 1. -## Interactions +#### Interactions | Unit / Subsystem | Role | |-------------------------|-------------------------------------------------------------------------| diff --git a/docs/design/build-mark/configuration/connector-config.md b/docs/design/build-mark/configuration/connector-config.md index 287e9fb9..4c2ec8ca 100644 --- a/docs/design/build-mark/configuration/connector-config.md +++ b/docs/design/build-mark/configuration/connector-config.md @@ -1,6 +1,6 @@ -# ConnectorConfig, GitHubConnectorConfig, AzureDevOpsConnectorConfig +### ConnectorConfig, GitHubConnectorConfig, AzureDevOpsConnectorConfig -## Overview +#### Overview These three configuration data models define the connector selection and per-connector settings read from the `connector:` section of `.buildmark.yaml`. @@ -9,9 +9,9 @@ settings read from the `connector:` section of `.buildmark.yaml`. settings. `GitHubConnectorConfig` holds GitHub-specific overrides. `AzureDevOpsConnectorConfig` holds Azure DevOps-specific connection details. -## Data Models +#### Data Models -### ConnectorConfig +##### ConnectorConfig | Property | Type | Description | |---------------|-------------------------------|-----------------------------------------------| @@ -19,7 +19,7 @@ holds Azure DevOps-specific connection details. | `GitHub` | `GitHubConnectorConfig?` | Optional GitHub connector settings | | `AzureDevOps` | `AzureDevOpsConnectorConfig?` | Optional Azure DevOps connector settings | -### GitHubConnectorConfig +##### GitHubConnectorConfig | Property | Type | Description | |-----------|-----------|---------------------------------------------------------------------| @@ -27,7 +27,7 @@ holds Azure DevOps-specific connection details. | `Repo` | `string?` | Repository name override | | `BaseUrl` | `string?` | Optional GitHub Enterprise API base URL; `null` uses the public API | -### AzureDevOpsConnectorConfig +##### AzureDevOpsConnectorConfig | Property | Type | Description | |-------------------|-----------|---------------------------------------------------------------------------| @@ -36,7 +36,7 @@ holds Azure DevOps-specific connection details. | `Project` | `string?` | Azure DevOps project name | | `Repository` | `string?` | Repository name within the project | -## Interactions +#### Interactions | Unit / Subsystem | Role | |-----------------------------|---------------------------------------------------------------------------------| diff --git a/docs/design/build-mark/configuration/report-config.md b/docs/design/build-mark/configuration/report-config.md index 12bb4668..e3e36b6e 100644 --- a/docs/design/build-mark/configuration/report-config.md +++ b/docs/design/build-mark/configuration/report-config.md @@ -1,12 +1,12 @@ -# ReportConfig +### ReportConfig -## Overview +#### Overview `ReportConfig` is a configuration data model holding the optional report output settings read from the `report:` section of `.buildmark.yaml`. All properties are nullable; when absent, `Program` uses CLI argument values or built-in defaults. -## Data Model +#### Data Model | Property | Type | Description | |----------------------|-----------|--------------------------------------------------------------------------------| @@ -14,7 +14,7 @@ absent, `Program` uses CLI argument values or built-in defaults. | `Depth` | `int?` | Optional heading depth for report sections; `null` defaults to 1 | | `IncludeKnownIssues` | `bool?` | Optional flag to include known issues; `null` defaults to `false` | -## Interactions +#### Interactions | Unit / Subsystem | Role | |--------------------------|-----------------------------------------------------------------------------------| diff --git a/docs/design/build-mark/configuration/rule-config.md b/docs/design/build-mark/configuration/rule-config.md index aba0cec2..61ac6cf2 100644 --- a/docs/design/build-mark/configuration/rule-config.md +++ b/docs/design/build-mark/configuration/rule-config.md @@ -1,6 +1,6 @@ -# RuleConfig and RuleMatchConfig +### RuleConfig and RuleMatchConfig -## Overview +#### Overview `RuleConfig` is a configuration data model representing a single item routing rule read from the `rules:` list in `.buildmark.yaml`. Each rule carries match conditions and a destination @@ -8,23 +8,23 @@ section ID. `RuleMatchConfig` holds the conditions that must be satisfied for a Both types are defined in `Configuration/RuleConfig.cs`. -## Data Models +#### Data Models -### RuleConfig +##### RuleConfig | Property | Type | Description | |----------|-------------------|---------------------------------------------------------| | `Match` | `RuleMatchConfig` | Match conditions (labels, work-item types) for the rule | | `Route` | `string` | Destination section `Id` for matched items | -### RuleMatchConfig +##### RuleMatchConfig | Property | Type | Description | |----------------|-----------------|-------------------------------------------------------------------| | `Label` | `IList` | List of label values; rule matches when any label is present | | `WorkItemType` | `IList` | List of work-item type values; rule matches when any type matches | -## Interactions +#### Interactions | Unit / Subsystem | Role | |-------------------------|-------------------------------------------------------------------------| diff --git a/docs/design/build-mark/configuration/section-config.md b/docs/design/build-mark/configuration/section-config.md index 658cc64b..21b3e74e 100644 --- a/docs/design/build-mark/configuration/section-config.md +++ b/docs/design/build-mark/configuration/section-config.md @@ -1,19 +1,19 @@ -# SectionConfig +### SectionConfig -## Overview +#### Overview `SectionConfig` is a configuration data model representing a single report section definition read from the `sections:` list in `.buildmark.yaml`. Each section has a unique identifier used by routing rules and a display title used as the markdown heading. -## Data Model +#### Data Model | Property | Type | Description | |----------|----------|--------------------------------------| | `Id` | `string` | Unique identifier for the section | | `Title` | `string` | Display title for the report section | -## Interactions +#### Interactions | Unit / Subsystem | Role | |-------------------------|-------------------------------------------------------------------------| diff --git a/docs/design/build-mark/program.md b/docs/design/build-mark/program.md index c3c0eadf..785d84ee 100644 --- a/docs/design/build-mark/program.md +++ b/docs/design/build-mark/program.md @@ -1,6 +1,6 @@ -# Program +## Program -## Overview +### 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 @@ -11,7 +11,7 @@ and a public method `Run`, which accepts an existing `Context` and performs the execution logic. `Run` is exposed separately so that integration tests can inject a pre-configured `Context` without repeating argument parsing. -## Data Model +### Data Model `Program` exposes a single static property: @@ -23,9 +23,9 @@ The version is resolved at startup by inspecting `AssemblyInformationalVersionAt first, then falling back to `assembly.GetName().Version`, and finally defaulting to `"0.0.0"` if neither attribute is present. -## Methods +### Methods -### `Main(string[] args) → int` +#### `Main(string[] args) → int` The application entry point (declared `private static`). It creates a `Context` from the supplied command-line arguments and delegates to `Run`. Any `ArgumentException` @@ -34,7 +34,7 @@ or `InvalidOperationException` is caught, written directly to `Console.Error` (n other exception is re-thrown after logging so the runtime can report an unhandled exception. -### `Run(Context context) → void` +#### `Run(Context context) → void` Executes the main program logic against an already-constructed `Context`. The method applies the following priority order: @@ -49,7 +49,7 @@ method applies the following priority order: The exit code is managed through `context.ExitCode` rather than as a return value. -### `ProcessBuildNotes(Context context)` +#### `ProcessBuildNotes(Context context)` Calls `BuildMarkConfigReader.ReadAsync` to load the optional `.buildmark.yaml` file, then calls `result.ReportTo(context)` to surface any configuration issues. @@ -81,23 +81,23 @@ If errors occurred, the method returns early. Otherwise: to the console and allows the exit code to reflect only semantic errors rather than I/O failures outside the tool's control. -### `PrintBanner(Context context)` +#### `PrintBanner(Context context)` Writes the application name, version, and copyright notice to the context output. Called unconditionally after the version-flag check in `Run`. -### `PrintHelp(Context context)` +#### `PrintHelp(Context context)` Writes the full usage message (command syntax, options list) to the context output. Called when any of the `-?`, `-h`, or `--help` flags is set. -### `LoadConfiguration() → ConfigurationLoadResult` +#### `LoadConfiguration() → ConfigurationLoadResult` Synchronously invokes `BuildMarkConfigReader.ReadAsync(Environment.CurrentDirectory)`. Called from both the lint branch of `Run` and from `ProcessBuildNotes` to keep the async-to-sync bridging in one place. -## Interactions +### Interactions | Unit / Subsystem | Role | |--------------------------|---------------------------------------------------------------------------------| diff --git a/docs/design/build-mark/repo-connectors/repo-connectors.md b/docs/design/build-mark/repo-connectors.md similarity index 96% rename from docs/design/build-mark/repo-connectors/repo-connectors.md rename to docs/design/build-mark/repo-connectors.md index cbc9d6dd..0388c307 100644 --- a/docs/design/build-mark/repo-connectors/repo-connectors.md +++ b/docs/design/build-mark/repo-connectors.md @@ -1,6 +1,6 @@ -# RepoConnectors Subsystem +## RepoConnectors Subsystem -## Overview +### Overview The RepoConnectors subsystem abstracts access to repository metadata for BuildMark. It provides an interface and base class for repository connectors, a factory for @@ -14,7 +14,7 @@ subsystem provides the production Azure DevOps REST connector, and the `Mock` subsystem provides the in-memory connector used by the built-in `--validate` self-test. -## Units +### Units - `IRepoConnector` - `RepoConnectors/IRepoConnector.cs` - interface for all repository connectors @@ -29,7 +29,7 @@ self-test. - `ItemControlsInfo` - `RepoConnectors/ItemControlsInfo.cs` - data record holding visibility, type, and version-set values -## Subsystems +### Subsystems - **`GitHub`** - `RepoConnectors/GitHub/` - `GitHubRepoConnector`, `GitHubGraphQLClient`, `GitHubGraphQLTypes` @@ -37,7 +37,7 @@ self-test. `AzureDevOpsRestClient`, `AzureDevOpsApiTypes`, `WorkItemMapper` - **`Mock`** - `RepoConnectors/Mock/` - `MockRepoConnector` (used by `--validate` self-test) -## Interfaces +### Interfaces `IRepoConnector` defines the contract for all connectors: @@ -45,7 +45,7 @@ self-test. |-------------------------------------|--------|----------------------------------| | `GetBuildInformationAsync(version)` | Method | Fetch complete build information | -## Interactions +### Interactions | Unit / Subsystem | Role | |------------------------------|------------------------------------------------------------------------| diff --git a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops.md b/docs/design/build-mark/repo-connectors/azure-devops.md similarity index 94% rename from docs/design/build-mark/repo-connectors/azure-devops/azure-devops.md rename to docs/design/build-mark/repo-connectors/azure-devops.md index 689f0c88..312dd3e7 100644 --- a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops.md +++ b/docs/design/build-mark/repo-connectors/azure-devops.md @@ -1,12 +1,12 @@ -# AzureDevOps Subsystem +### AzureDevOps Subsystem -## Overview +#### Overview The AzureDevOps subsystem groups the units responsible for querying the Azure DevOps REST API. It sits within the RepoConnectors subsystem and provides the production connector used when the repository host is Azure DevOps. -## Units +#### Units - `AzureDevOpsRepoConnector` - `RepoConnectors/AzureDevOps/AzureDevOpsRepoConnector.cs` - implements `IRepoConnector` for Azure DevOps. @@ -17,7 +17,7 @@ connector used when the repository host is Azure DevOps. - `WorkItemMapper` - `RepoConnectors/AzureDevOps/WorkItemMapper.cs` - maps Azure DevOps work items to `ItemInfo` objects. -### `AzureDevOpsRepoConnector` +##### `AzureDevOpsRepoConnector` The primary production connector. Resolves the repository URL, organization, and project from the environment or configuration, creates an `AzureDevOpsRestClient`, fetches all @@ -25,19 +25,19 @@ required data via REST APIs, applies item-controls overrides from buildmark bloc custom fields, calls `ItemRouter` to assign items to sections, and assembles the `BuildInformation` record. -### `AzureDevOpsRestClient` +##### `AzureDevOpsRestClient` Handles HTTPS communication with the Azure DevOps REST API endpoint. Supports paginated requests and authenticates via a `Basic` or `Bearer` authorization header. Supports both cloud (`dev.azure.com`) and on-premises Azure DevOps Server instances via configurable organization URL. -### `AzureDevOpsApiTypes` +##### `AzureDevOpsApiTypes` Internal C# records that mirror the REST API response types returned by Azure DevOps. Used as the deserialization target for responses from `AzureDevOpsRestClient`. -### `WorkItemMapper` +##### `WorkItemMapper` Maps `AzureDevOpsWorkItem` records from the REST API into `ItemInfo` records for the `BuildInformation` model. Extracts visibility, type, and affected-version controls from @@ -45,7 +45,7 @@ both buildmark code blocks in the work item description and Azure DevOps custom (`Custom.Visibility`, `Custom.AffectedVersions`). Custom fields take precedence over buildmark blocks when both are present. -## Interactions +#### Interactions | Unit / Subsystem | Role | |-------------------------------|---------------------------------------------------------------------------| diff --git a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md index 3e1ec1d3..b3605f6f 100644 --- a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md +++ b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md @@ -1,6 +1,6 @@ -# AzureDevOpsApiTypes +#### AzureDevOpsApiTypes -## Overview +##### Overview `AzureDevOpsApiTypes` is the collection of internal record types used by the Azure DevOps subsystem to represent REST API request and response payloads. These @@ -8,7 +8,7 @@ types allow `AzureDevOpsRestClient` to deserialize Azure DevOps API responses in strongly typed objects that `AzureDevOpsRepoConnector` and `WorkItemMapper` can process safely and predictably. -## Responsibilities +##### Responsibilities - Represent repository, commit, pull request, and work item response objects - Carry pagination metadata (`AzureDevOpsCollectionResponse`) @@ -18,7 +18,7 @@ process safely and predictably. `AzureDevOpsRestClient` can deserialize API responses without reflection workarounds or third-party JSON libraries -## Key Types +##### Key Types All record types are defined as C# `record` types with init-only properties using conventional PascalCase property names. No `[JsonPropertyName]` attributes are @@ -31,25 +31,25 @@ strings. The sole exception is `AzureDevOpsWorkItem.Fields`, which is deserialized as a `Dictionary` and preserves the dotted field-reference-name keys (e.g. `System.WorkItemType`) verbatim. -### `AzureDevOpsRepository` +###### `AzureDevOpsRepository` Repository metadata returned by the repository lookup endpoint. Fields: `id`, `name`, `remoteUrl` -### `AzureDevOpsCommit` +###### `AzureDevOpsCommit` Commit data returned by the commits endpoint. Fields: `commitId`, `comment` -### `AzureDevOpsGitCommitRef` +###### `AzureDevOpsGitCommitRef` Minimal Git commit reference containing only the commit SHA. Fields: `commitId` -### `AzureDevOpsPullRequest` +###### `AzureDevOpsPullRequest` Pull request data returned by the pull requests endpoint. @@ -61,7 +61,7 @@ representing the commit of the most recent pull request merge. The type exposes a computed `MergeCommitId` property that returns `LastMergeCommit?.CommitId`, providing a convenient nullable string accessor for the merge commit SHA. -### `AzureDevOpsWorkItem` +###### `AzureDevOpsWorkItem` Work item data returned by the work items endpoint with all fields expanded. @@ -78,13 +78,13 @@ Key dictionary entries: | `Custom.Visibility` | Optional visibility override (`public`/`internal`)| | `Custom.AffectedVersions` | Optional affected version range expression | -### `AzureDevOpsWorkItemRef` +###### `AzureDevOpsWorkItemRef` Work item id reference returned by WIQL queries and pull request work item links. Fields: `id`, `url` -### `AzureDevOpsRef` +###### `AzureDevOpsRef` Git reference (tag or branch) returned by the Azure DevOps refs endpoint. @@ -98,19 +98,19 @@ tags. The type exposes a computed `CommitId` property that returns `PeeledObjectId ?? ObjectId`, providing the resolved commit SHA regardless of tag type. -### `AzureDevOpsWorkItemQuery` +###### `AzureDevOpsWorkItemQuery` Result of a WIQL query, used to identify open work items matching a given filter. Fields: `workItems` (list of id references) -### `AzureDevOpsCollectionResponse` +###### `AzureDevOpsCollectionResponse` Generic wrapper for paginated collection responses from the Azure DevOps REST API. Fields: `count`, `value` (list of `T`) -## Interactions +##### Interactions - `AzureDevOpsRestClient` uses these records as serialization and deserialization targets for REST API HTTP traffic. diff --git a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md index db53f9a9..61d656c0 100644 --- a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md +++ b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md @@ -1,6 +1,6 @@ -# AzureDevOpsRepoConnector +#### AzureDevOpsRepoConnector -## Overview +##### Overview `AzureDevOpsRepoConnector` is the production unit in the RepoConnectors/AzureDevOps subsystem. It implements `RepoConnectorBase` and uses `AzureDevOpsRestClient` to @@ -10,9 +10,9 @@ The unit reads the repository URL and current commit hash from Git, resolves the Azure DevOps token from environment variables, and fetches all data needed to construct a `BuildInformation` record. -## Data Model +##### Data Model -### Authentication +###### Authentication The connector resolves the Azure DevOps token using the following priority order: @@ -26,7 +26,7 @@ The connector resolves the Azure DevOps token using the following priority order If no token is found, the connector throws `InvalidOperationException`. -### Work Item Type Mapping +###### Work Item Type Mapping Azure DevOps work item types are mapped to normalized types: @@ -42,7 +42,7 @@ When routing rules are configured via `.buildmark.yaml`, the type-derived categorization is overridden by `RepoConnectorBase.ApplyRules`, which delegates to `ItemRouter` to distribute all collected items into the configured report sections. -### Item Controls Override +###### Item Controls Override After the work-item-type-derived categorization is determined, the connector calls `ItemControlsParser.Parse(description)` on the description body of each work item @@ -71,7 +71,7 @@ Custom fields take precedence over buildmark blocks when both are present. When neither a `buildmark` block nor custom fields are present, the existing work-item-type-based rules apply unchanged. -### REST API Response Types +###### REST API Response Types The `AzureDevOpsRestClient` returns the following record types: @@ -93,9 +93,9 @@ The `AzureDevOpsRestClient` returns the following record types: - **`AzureDevOpsCollectionResponse`** - wraps paginated responses with a count and value list. -## Methods +##### Methods -### `ParseAzureDevOpsUrl(url) → (organizationUrl, project, repository)` +###### `ParseAzureDevOpsUrl(url) → (organizationUrl, project, repository)` Internal utility that parses a Git remote URL into organization URL, project name, and repository name. Supports the following URL formats: @@ -109,7 +109,7 @@ name, and repository name. Supports the following URL formats: Throws `ArgumentException` when the URL does not match any supported format. -### `GetBuildInformationAsync(VersionTag? version) → BuildInformation` +###### `GetBuildInformationAsync(VersionTag? version) → BuildInformation` Main entry point. Performs the following steps: @@ -152,7 +152,7 @@ Main entry point. Performs the following steps: are configured, items remain in the legacy `Changes`, `Bugs`, and `KnownIssues` lists. Return the assembled `BuildInformation` record. -## Interactions +##### Interactions - `AzureDevOpsConnectorConfig` is received from `RepoConnectorFactory` and overrides the organization URL, project, and repository name. diff --git a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md index 89e5aa66..e793d887 100644 --- a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md +++ b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md @@ -1,13 +1,13 @@ -# AzureDevOpsRestClient +#### AzureDevOpsRestClient -## Overview +##### Overview `AzureDevOpsRestClient` is the Azure DevOps subsystem unit responsible for issuing paginated REST API requests to the Azure DevOps API and translating the responses into typed records for connector consumption. `AzureDevOpsRepoConnector` delegates all Azure DevOps API communication to this client. -## Authentication +##### Authentication The client authenticates using either: @@ -21,7 +21,7 @@ The client authenticates using either: The authentication scheme is selected automatically based on the token source resolved by `AzureDevOpsRepoConnector`. -## JSON Deserialization +##### JSON Deserialization The client uses `System.Net.Http.Json` extension methods (part of the .NET runtime) to deserialize Azure DevOps REST API responses. Specifically, each HTTP response body is @@ -38,12 +38,12 @@ The sole exception is the `AzureDevOpsWorkItem.Fields` dictionary - its keys are Azure DevOps field reference names (e.g. `System.WorkItemType`, `Custom.Visibility`) and are preserved as-is without any naming transformation. -## Methods +##### Methods The client provides the following methods for retrieving the repository data needed to build a `BuildInformation` record: -### `GetRepositoryAsync(repository)` +###### `GetRepositoryAsync(repository)` Fetches repository metadata for the specified repository. @@ -52,7 +52,7 @@ Endpoint: `GET /{organization}/{project}/_apis/git/repositories/{repository}?api Returns an `AzureDevOpsRepository` record containing the repository id, name, and remote URL. -### `GetTagsAsync(repositoryId)` +###### `GetTagsAsync(repositoryId)` Fetches all tag references for the specified repository. @@ -64,7 +64,7 @@ peeled commit SHA. The `peelTags=true` query parameter instructs the API to reso annotated tag objects to their underlying commit SHA, which is returned in the `peeledObjectId` field. -### `GetCommitsAsync(repositoryId)` +###### `GetCommitsAsync(repositoryId)` Fetches the complete paginated commit history for the repository. @@ -73,7 +73,7 @@ Endpoint: `GET /{organization}/{project}/_apis/git/repositories/{id}/commits?api Returns a list of `AzureDevOpsCommit` records. Automatically paginates using `$top` and `$skip` query parameters to retrieve all pages. -### `GetPullRequestsAsync(repositoryId, status)` +###### `GetPullRequestsAsync(repositoryId, status)` Fetches all pull requests with the specified status for the repository. Supports `all`, `active`, `completed`, and `abandoned` status values. @@ -83,7 +83,7 @@ Endpoint: `GET /{organization}/{project}/_apis/git/repositories/{id}/pullrequest Returns a list of `AzureDevOpsPullRequest` records. Automatically paginates using `$top` and `$skip` query parameters to retrieve all pages. -### `GetPullRequestWorkItemsAsync(repositoryId, pullRequestId)` +###### `GetPullRequestWorkItemsAsync(repositoryId, pullRequestId)` Fetches the work items linked to a specific pull request. @@ -92,7 +92,7 @@ Endpoint: `GET /{organization}/{project}/_apis/git/repositories/{id}/pullrequest Returns a list of work item id references from the `AzureDevOpsCollectionResponse`. -### `GetWorkItemsAsync(workItemIds)` +###### `GetWorkItemsAsync(workItemIds)` Batch-fetches work item details for a list of work item ids. Splits requests into batches of 200 ids as required by the Azure DevOps API. @@ -101,7 +101,7 @@ Endpoint: `GET /{organization}/{project}/_apis/wit/workitems?ids={ids}&$expand=a Returns a list of `AzureDevOpsWorkItem` records with all fields expanded. -### `QueryWorkItemsAsync(wiql)` +###### `QueryWorkItemsAsync(wiql)` Executes a WIQL (Work Item Query Language) query and returns the matching work item id references. @@ -111,7 +111,7 @@ Endpoint: `POST /{organization}/{project}/_apis/wit/wiql?api-version=6.0` Returns an `AzureDevOpsWorkItemQuery` record containing the list of matching work item id references. -## Interactions +##### Interactions - `AzureDevOpsRepoConnector` creates and calls `AzureDevOpsRestClient`. - `AzureDevOpsApiTypes` provides the request and response record types used for diff --git a/docs/design/build-mark/repo-connectors/azure-devops/work-item-mapper.md b/docs/design/build-mark/repo-connectors/azure-devops/work-item-mapper.md index 04110c49..6c9642b0 100644 --- a/docs/design/build-mark/repo-connectors/azure-devops/work-item-mapper.md +++ b/docs/design/build-mark/repo-connectors/azure-devops/work-item-mapper.md @@ -1,15 +1,15 @@ -# WorkItemMapper +#### WorkItemMapper -## Overview +##### Overview `WorkItemMapper` maps `AzureDevOpsWorkItem` records from the Azure DevOps REST API into `ItemInfo` records for the `BuildInformation` model. It centralizes work item type normalization, state-based filtering, and item-controls extraction from both buildmark code blocks in work item description bodies and Azure DevOps custom fields. -## Data Model +##### Data Model -### Work Item Type Mapping +###### Work Item Type Mapping Azure DevOps work item types are mapped to normalized types for the `ItemInfo` model: @@ -19,7 +19,7 @@ Azure DevOps work item types are mapped to normalized types for the `ItemInfo` m | `User Story`, `Feature`, `Epic` | `"feature"` | | `Task`, `Test Case`, etc. | work item type | -### Work Item State Filtering +###### Work Item State Filtering When identifying known issues, only work items in an unresolved state are included. The following state values are treated as resolved and excluded from known-issues @@ -32,7 +32,7 @@ reporting: All other state values (e.g. `Active`, `New`, `In Progress`) are treated as unresolved and included in known-issues reporting. -### Item Controls Extraction +###### Item Controls Extraction Item controls are extracted from two sources and merged: @@ -47,9 +47,9 @@ Item controls are extracted from two sources and merged: present for the same control. If a custom field value is non-null, it supersedes the corresponding value from the buildmark block. -## Methods +##### Methods -### `MapWorkItemToItemInfo(workItem)` +###### `MapWorkItemToItemInfo(workItem)` Maps a single `AzureDevOpsWorkItem` to an `ItemInfo` record. @@ -65,7 +65,7 @@ Steps: 6. Construct and return the `ItemInfo` record with the title, url, type, and affected versions. -### `IsWorkItemResolved(workItem)` +###### `IsWorkItemResolved(workItem)` Checks whether a work item's state is one of the known resolved states (`Resolved`, `Closed`, `Done`). @@ -74,13 +74,13 @@ Returns `true` if the work item is resolved; `false` otherwise. Used by `AzureDevOpsRepoConnector` to filter out resolved work items when collecting known issues. -### `GetWorkItemTypeForRuleMatching(workItem)` +###### `GetWorkItemTypeForRuleMatching(workItem)` Returns the work item type string used for routing rule matching. This is the raw `System.WorkItemType` value from the work item's fields dictionary, allowing routing rules in `.buildmark.yaml` to match on Azure DevOps-native work item type names. -### `ExtractItemControls(workItem)` +###### `ExtractItemControls(workItem)` Combines item controls from both buildmark blocks and custom fields into a single `ItemControlsInfo?` record. @@ -93,7 +93,7 @@ Steps: block result. 4. Return the merged `ItemControlsInfo`, or `null` if no controls were found. -## Interactions +##### Interactions - `AzureDevOpsRepoConnector` calls `WorkItemMapper` to convert REST API work item records into `ItemInfo` records. diff --git a/docs/design/build-mark/repo-connectors/github/github.md b/docs/design/build-mark/repo-connectors/github.md similarity index 93% rename from docs/design/build-mark/repo-connectors/github/github.md rename to docs/design/build-mark/repo-connectors/github.md index de45e608..29b011d8 100644 --- a/docs/design/build-mark/repo-connectors/github/github.md +++ b/docs/design/build-mark/repo-connectors/github.md @@ -1,12 +1,12 @@ -# GitHub Subsystem +### GitHub Subsystem -## Overview +#### Overview The GitHub subsystem groups the units responsible for querying the GitHub GraphQL API. It sits within the RepoConnectors subsystem and provides the production connector used when the repository host is GitHub or GitHub Enterprise. -## Units +#### Units - `GitHubRepoConnector` - `RepoConnectors/GitHub/GitHubRepoConnector.cs` - implements `IRepoConnector` for GitHub. @@ -15,25 +15,25 @@ production connector used when the repository host is GitHub or GitHub Enterpris - `GitHubGraphQLTypes` - `RepoConnectors/GitHub/GitHubGraphQLTypes.cs` - provides record types for GraphQL request and response data. -### `GitHubRepoConnector` +##### `GitHubRepoConnector` The primary production connector. Resolves the repository URL and GitHub token from the environment, creates a `GitHubGraphQLClient`, fetches all required data via GraphQL, applies item-controls overrides, calls `ItemRouter` to assign items to sections, and assembles the `BuildInformation` record. -### `GitHubGraphQLClient` +##### `GitHubGraphQLClient` Handles HTTPS communication with the GitHub GraphQL endpoint. Supports paginated queries and authenticates via an `Authorization: bearer ` header. Also supports GitHub Enterprise by accepting an alternative base URL. -### `GitHubGraphQLTypes` +##### `GitHubGraphQLTypes` Internal C# records that mirror the GraphQL schema types returned by GitHub. Used as the deserialization target for responses from `GitHubGraphQLClient`. -## Interactions +#### Interactions | Unit / Subsystem | Role | |-------------------------|-------------------------------------------------------------------| diff --git a/docs/design/build-mark/repo-connectors/github/github-graphql-client.md b/docs/design/build-mark/repo-connectors/github/github-graphql-client.md index 2768fe19..d3544bcd 100644 --- a/docs/design/build-mark/repo-connectors/github/github-graphql-client.md +++ b/docs/design/build-mark/repo-connectors/github/github-graphql-client.md @@ -1,13 +1,13 @@ -# GitHubGraphQLClient +#### GitHubGraphQLClient -## Overview +##### Overview `GitHubGraphQLClient` is the GitHub subsystem unit responsible for issuing paginated GraphQL requests to the GitHub API and translating the responses into typed records for connector consumption. `GitHubRepoConnector` delegates all GitHub API communication to this client. -## Constructors +##### Constructors The class provides two constructors: @@ -17,7 +17,7 @@ The class provides two constructors: - **Internal constructor** - accepts an existing `HttpClient` directly. Used by tests to inject a mock `HttpClient` without network access. -## Lifecycle +##### Lifecycle `GitHubGraphQLClient` implements `IDisposable`. When created via the public constructor, the instance owns its `HttpClient` and disposes it when the client @@ -28,14 +28,14 @@ Callers that construct `GitHubGraphQLClient` via the public constructor must wrap usage in a `using` statement or otherwise dispose the instance to release the underlying HTTP connection resources. -## Error Strategy +##### Error Strategy All API methods catch exceptions from the underlying `HttpClient` and return empty lists rather than propagating the exception to the caller. This allows the connector to continue with partial data when the GitHub API is transiently unavailable. -## Methods +##### Methods The client provides methods for retrieving the repository data needed to build a `BuildInformation` record: @@ -47,7 +47,7 @@ The client provides methods for retrieving the repository data needed to build a - `GetAllIssuesAsync` for issue data, including description bodies - `FindIssueIdsLinkedToPullRequestAsync` for cross-link lookups -## Interactions +##### Interactions - `GitHubRepoConnector` creates and calls `GitHubGraphQLClient`. - `GitHubGraphQLTypes` provide the request and response record types used for diff --git a/docs/design/build-mark/repo-connectors/github/github-graphql-types.md b/docs/design/build-mark/repo-connectors/github/github-graphql-types.md index 75efb0a0..0e095357 100644 --- a/docs/design/build-mark/repo-connectors/github/github-graphql-types.md +++ b/docs/design/build-mark/repo-connectors/github/github-graphql-types.md @@ -1,20 +1,20 @@ -# GitHubGraphQLTypes +#### GitHubGraphQLTypes -## Overview +##### Overview `GitHubGraphQLTypes` is the collection of internal record types used by the GitHub subsystem to represent GraphQL request and response payloads. These types allow `GitHubGraphQLClient` to deserialize GitHub API responses into strongly typed objects that `GitHubRepoConnector` can process safely and predictably. -## Responsibilities +##### Responsibilities - Represent tag, release, issue, pull request, and commit response nodes - Carry pagination cursors and connection metadata - Preserve issue and pull request description body fields for item-controls parsing -## Interactions +##### Interactions - `GitHubGraphQLClient` uses these records as serialization and deserialization targets for GraphQL HTTP traffic. diff --git a/docs/design/build-mark/repo-connectors/github/github-repo-connector.md b/docs/design/build-mark/repo-connectors/github/github-repo-connector.md index 056fc181..cbf404b0 100644 --- a/docs/design/build-mark/repo-connectors/github/github-repo-connector.md +++ b/docs/design/build-mark/repo-connectors/github/github-repo-connector.md @@ -1,6 +1,6 @@ -# GitHubRepoConnector +#### GitHubRepoConnector -## Overview +##### Overview `GitHubRepoConnector` is the production unit in the RepoConnectors/GitHub subsystem. It implements `RepoConnectorBase` and uses `GitHubGraphQLClient` to @@ -10,9 +10,9 @@ 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 +##### Data Model -### Authentication +###### Authentication The connector resolves the GitHub token using the following priority order: @@ -22,7 +22,7 @@ The connector resolves the GitHub token using the following priority order: If no token is found, the connector throws `InvalidOperationException`. -### Label Mapping +###### Label Mapping GitHub issue and pull request labels are mapped to normalized types: @@ -40,7 +40,7 @@ When routing rules are configured via `.buildmark.yaml`, the label-derived categ is overridden by `RepoConnectorBase.ApplyRules`, which delegates to `ItemRouter` to distribute all collected items into the configured report sections instead. -### GraphQL Response Types +###### GraphQL Response Types The `GitHubGraphQLClient` returns `PullRequestNode` and `IssueNode` records that must include the `body` field so the connector can pass description text to @@ -75,7 +75,7 @@ internal record IssueNode( Both `GetPullRequestsAsync` and `GetAllIssuesAsync` must include `body` in their GraphQL field selections. -### Item Controls Override +###### Item Controls Override After the label-derived type is determined, the connector calls `ItemControlsParser.Parse(body)` on the description body of each issue and pull @@ -95,9 +95,9 @@ overrides are applied: When no `buildmark` block is present, the existing label-based rules apply unchanged. -## Methods +##### Methods -### `GetBuildInformationAsync(Version? version) → BuildInformation` +###### `GetBuildInformationAsync(Version? version) → BuildInformation` Main entry point. Performs the following steps: @@ -140,7 +140,7 @@ Main entry point. Performs the following steps: 13. Generate the full changelog URL from the baseline and target tags. 14. Return the assembled `BuildInformation` record. -## Interactions +##### Interactions - `GitHubConnectorConfig` is received from `RepoConnectorFactory` and overrides the owner, repository, and URL. diff --git a/docs/design/build-mark/repo-connectors/item-controls-info.md b/docs/design/build-mark/repo-connectors/item-controls-info.md index 5f4c4285..628131ec 100644 --- a/docs/design/build-mark/repo-connectors/item-controls-info.md +++ b/docs/design/build-mark/repo-connectors/item-controls-info.md @@ -1,13 +1,13 @@ -# ItemControlsInfo +### ItemControlsInfo -## Overview +#### Overview `ItemControlsInfo` is the data record used by the RepoConnectors subsystem to carry the controls extracted from a `buildmark` block. It stores the optional visibility override, type override, and affected-version interval data that `GitHubRepoConnector` applies while constructing `ItemInfo` records. -## Data Model +#### Data Model ```csharp public record ItemControlsInfo( @@ -22,7 +22,7 @@ public record ItemControlsInfo( - `AffectedVersions` (`VersionIntervalSet?`) stores the optional affected-version interval set. -## Interactions +#### Interactions - `ItemControlsParser` creates an `ItemControlsInfo` instance when a `buildmark` block contains one or more recognized keys. diff --git a/docs/design/build-mark/repo-connectors/item-controls-parser.md b/docs/design/build-mark/repo-connectors/item-controls-parser.md index 8a6e6a64..8b59adf7 100644 --- a/docs/design/build-mark/repo-connectors/item-controls-parser.md +++ b/docs/design/build-mark/repo-connectors/item-controls-parser.md @@ -1,6 +1,6 @@ -# ItemControlsParser and ItemControlsInfo +### ItemControlsParser and ItemControlsInfo -## Overview +#### Overview `ItemControlsParser` is a static utility class that extracts a `buildmark` fenced code block from an issue or pull request description and parses its @@ -10,7 +10,7 @@ method returns `null` so that callers can apply default label-based rules. `ItemControlsInfo` is the immutable data record produced by the parser. It holds up to three optional fields: `Visibility`, `Type`, and `AffectedVersions`. -## Block Detection +#### Block Detection The parser locates a `buildmark` block using the following rules: @@ -24,7 +24,7 @@ The parser locates a `buildmark` block using the following rules: itself. 5. If no such block is found, `Parse` returns `null`. -## Key-Value Parsing +#### Key-Value Parsing Each non-empty line inside the block is treated as a `key: value` pair: @@ -48,13 +48,13 @@ Recognized keys: Unrecognized values for a known key are silently ignored (the field remains `null`). -## Data Model - ItemControlsInfo +#### Data Model - ItemControlsInfo See `item-controls-info.md` for the `ItemControlsInfo` data model definition. -## Methods +#### Methods -### `ItemControlsParser.Parse(string? description) → ItemControlsInfo?` +##### `ItemControlsParser.Parse(string? description) → ItemControlsInfo?` Entry point for the parser. Steps: @@ -68,7 +68,7 @@ Entry point for the parser. Steps: 7. Build and return an `ItemControlsInfo` from the recognized keys, or `null` if no recognized keys were found. -## Interactions +#### Interactions | Unit / Subsystem | Role | |-----------------------|---------------------------------------------------------------------------------| diff --git a/docs/design/build-mark/repo-connectors/item-router.md b/docs/design/build-mark/repo-connectors/item-router.md index 55738127..d55b18b9 100644 --- a/docs/design/build-mark/repo-connectors/item-router.md +++ b/docs/design/build-mark/repo-connectors/item-router.md @@ -1,6 +1,6 @@ -# ItemRouter +### ItemRouter -## Overview +#### Overview `ItemRouter` is a shared static utility in the RepoConnectors subsystem that routes a list of `ItemInfo` objects into report sections. It applies a list of `RuleConfig` @@ -10,9 +10,9 @@ routing logic across multiple connector implementations. All connectors (GitHub, Azure DevOps, Mock) call `ItemRouter` rather than each implementing their own routing. -## Methods +#### Methods -### `Route(items, rules, sections) → Dictionary>` +##### `Route(items, rules, sections) → Dictionary>` Takes a list of `ItemInfo` objects, a list of `RuleConfig` entries, and a list of `SectionConfig` entries, and returns a dictionary mapping each section ID to the @@ -23,7 +23,7 @@ items assigned to that section. sections - `sections` (`IReadOnlyList`) - ordered list of report sections -#### Algorithm +###### Algorithm Rules are evaluated in order; the first matching rule wins. Items that do not match any rule are placed in the **default section**, which is the first entry in the @@ -36,21 +36,21 @@ Sections not present in the configured `sections` list are created dynamically when a rule routes an item to an unknown section ID. This allows rules to introduce ad-hoc sections without requiring them to be pre-declared. -#### Rule matching +###### Rule matching - A `null` `Match` block is a **catch-all** - the rule matches every item. - A non-null `Match` block may specify `Label` and/or `WorkItemType` filter lists. Both lists are matched case-insensitively against the item's `Type` field. All non-empty filter lists must match for the rule to apply. -#### Error Handling +###### Error Handling No explicit error handling is performed. Callers are responsible for passing valid, non-null arguments. Duplicate section IDs in the `sections` list will cause an `ArgumentException` from the internal dictionary initialization. Null inputs will result in a `NullReferenceException` propagating to the caller. -## Interactions +#### Interactions - `ItemInfo` provides the input items to be routed from the BuildNotes subsystem. diff --git a/docs/design/build-mark/repo-connectors/mock/mock.md b/docs/design/build-mark/repo-connectors/mock.md similarity index 94% rename from docs/design/build-mark/repo-connectors/mock/mock.md rename to docs/design/build-mark/repo-connectors/mock.md index 32fdd7a3..c10a8ef0 100644 --- a/docs/design/build-mark/repo-connectors/mock/mock.md +++ b/docs/design/build-mark/repo-connectors/mock.md @@ -1,6 +1,6 @@ -# Mock Subsystem +### Mock Subsystem -## Overview +#### Overview The Mock subsystem groups the in-memory connector used by the built-in `--validate` self-test. It sits within the RepoConnectors subsystem. @@ -9,13 +9,13 @@ The Mock subsystem groups the in-memory connector used by the built-in the `--validate` flag must work in any deployment without requiring a separate test assembly or external tooling. -## Units +#### Units | Unit | File | Responsibility | |----------------------|---------------------------------------------|----------------------------------------------| | `MockRepoConnector` | `RepoConnectors/Mock/MockRepoConnector.cs` | In-memory connector for self-validation | -## Interactions +#### Interactions | Unit / Subsystem | Role | |---------------------|-------------------------------------------------------------------| diff --git a/docs/design/build-mark/repo-connectors/mock/mock-repo-connector.md b/docs/design/build-mark/repo-connectors/mock/mock-repo-connector.md index 2ac61226..12c9018b 100644 --- a/docs/design/build-mark/repo-connectors/mock/mock-repo-connector.md +++ b/docs/design/build-mark/repo-connectors/mock/mock-repo-connector.md @@ -1,6 +1,6 @@ -# MockRepoConnector +#### MockRepoConnector -## Overview +##### Overview `MockRepoConnector` is an in-memory implementation of `IRepoConnector` used for self-validation and unit testing. It returns a fixed, deterministic dataset @@ -10,7 +10,7 @@ without making any network or filesystem calls. the `--validate` flag must work in any deployment without requiring a separate test assembly or external tooling. -## Data Model +##### Data Model The connector holds hard-coded mappings used to build the `BuildInformation` response: @@ -23,9 +23,9 @@ The connector holds hard-coded mappings used to build the `BuildInformation` res | `_openIssues` | `List` | IDs of issues that remain open | | `_issueAffectedVersions` | `Dictionary` | Issue ID -> declared affected-versions range | -## Methods +##### Methods -### `GetBuildInformationAsync(version?) → BuildInformation` +###### `GetBuildInformationAsync(version?) → BuildInformation` Resolves tag history and the current commit hash from the internal dictionaries, determines the target and baseline versions, collects changes and known issues, @@ -44,7 +44,7 @@ collects all items and passes them to `ApplyRules` (inherited from `RepoConnecto to produce the `RoutedSections` list. If no rules are configured, the legacy categorization into `Changes` and `Bugs` is used. -## Error Conditions +##### Error Conditions `GetBuildInformationAsync` throws `InvalidOperationException` in the following scenarios: @@ -57,7 +57,7 @@ These conditions mirror the equivalent error paths in the production `GitHubRepo and `AzureDevOpsRepoConnector`, making the mock suitable for testing error-handling code paths as well as the happy path. -## Interactions +##### Interactions | Unit / Subsystem | Role | |--------------------------|-----------------------------------------------------------------------------------| diff --git a/docs/design/build-mark/repo-connectors/repo-connector-base.md b/docs/design/build-mark/repo-connectors/repo-connector-base.md index 2dfc0ba2..b0fb977f 100644 --- a/docs/design/build-mark/repo-connectors/repo-connector-base.md +++ b/docs/design/build-mark/repo-connectors/repo-connector-base.md @@ -1,12 +1,12 @@ -# IRepoConnector and RepoConnectorBase +### IRepoConnector and RepoConnectorBase -## Overview +#### Overview `IRepoConnector` defines the contract that all repository connectors must satisfy. `RepoConnectorBase` is an abstract class implementing `IRepoConnector` and providing shared utilities used by concrete connectors. -## Interface +#### Interface `IRepoConnector` exposes a single method: @@ -14,7 +14,7 @@ shared utilities used by concrete connectors. |-------------------------------------|--------|----------------------------------| | `GetBuildInformationAsync(version)` | Method | Fetch complete build information | -## Base Class +#### Base Class `RepoConnectorBase` provides: @@ -26,26 +26,26 @@ shared utilities used by concrete connectors. | `RunCommandAsync(command, args)` | Protected virtual | Delegates shell commands to ProcessRunner | | `FindVersionIndex(versions, target)` | Protected static | Locates version using semantic equality | -### `Configure(rules, sections)` +##### `Configure(rules, sections)` Stores the routing rules and section definitions on the connector instance. Called by `Program.ProcessBuildNotes` after the connector is created, passing `Rules` and `Sections` from the loaded `.buildmark.yaml` configuration. -### `HasRules` +##### `HasRules` Protected boolean property that returns `true` when at least one rule has been stored via `Configure`. Concrete connectors use this in `GetBuildInformationAsync` to decide whether to call `ApplyRules` or use legacy categorization. -### `ApplyRules(allItems)` +##### `ApplyRules(allItems)` Routes the provided items using `ItemRouter.Route`, then assembles an ordered list of `(SectionId, SectionTitle, Items)` tuples following the configured section order. Any items routed to section IDs not in the configured section list are appended at the end using the section ID as the display title. -### `FindVersionIndex(versions, targetVersion)` +##### `FindVersionIndex(versions, targetVersion)` Protected static method that finds the index of a `targetVersion` within a list of `VersionTag` instances using **semantic VersionComparable equality**. This design @@ -62,7 +62,7 @@ The `RunCommandAsync` method accepts a command and a `params string[]` arguments array, and is `virtual` so that test subclasses can override it with mock implementations that return fixed strings without spawning real processes. -## Interactions +#### Interactions - `ProcessRunner` is used by `RunCommandAsync` to execute shell commands in the Utilities subsystem. diff --git a/docs/design/build-mark/repo-connectors/repo-connector-factory.md b/docs/design/build-mark/repo-connectors/repo-connector-factory.md index 19667503..80b2b44a 100644 --- a/docs/design/build-mark/repo-connectors/repo-connector-factory.md +++ b/docs/design/build-mark/repo-connectors/repo-connector-factory.md @@ -1,13 +1,13 @@ -# RepoConnectorFactory +### RepoConnectorFactory -## Overview +#### Overview `RepoConnectorFactory` is a static factory class that creates the appropriate `IRepoConnector` implementation based on the runtime environment. -## Methods +#### Methods -### `Create(ConnectorConfig? config) → IRepoConnector` +##### `Create(ConnectorConfig? config) → IRepoConnector` The factory method accepts an optional `ConnectorConfig` from the parsed `.buildmark.yaml` file and returns the appropriate @@ -39,7 +39,7 @@ library by external callers, so this design reflects the tool-oriented execution model rather than a guarantee that synchronization-context-related deadlocks are impossible in every host. -### `CreateFromRemoteUrl(ConnectorConfig? config, string? remoteUrl) → IRepoConnector` *(internal)* +##### `CreateFromRemoteUrl(ConnectorConfig? config, string? remoteUrl) → IRepoConnector` *(internal)* An internal helper that selects a connector based on `remoteUrl` alone (skipping environment-variable checks). It is exposed internally so that unit tests can @@ -52,7 +52,7 @@ exercise the URL-based detection logic without requiring a real git process. - If `remoteUrl` is `null` or does not match any known host, defaults to a `GitHubRepoConnector` initialized with `config?.GitHub`. -## Interactions +#### Interactions | Unit / Subsystem | Role | | ---------------------------- | ---------------------------------------------------------------------- | diff --git a/docs/design/build-mark/self-test/self-test.md b/docs/design/build-mark/self-test.md similarity index 95% rename from docs/design/build-mark/self-test/self-test.md rename to docs/design/build-mark/self-test.md index be655be5..8fafa56a 100644 --- a/docs/design/build-mark/self-test/self-test.md +++ b/docs/design/build-mark/self-test.md @@ -1,6 +1,6 @@ -# SelfTest Subsystem +## SelfTest Subsystem -## Overview +### 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 @@ -9,13 +9,13 @@ in the current environment, using a `MockRepoConnector` to avoid external API ca The subsystem has no dependencies on the Cli subsystem beyond receiving a `Context` as its input parameter. -## Units +### Units | Unit | File | Responsibility | |--------------|--------------------------|----------------------------------------------| | `Validation` | `SelfTest/Validation.cs` | Runs self-tests and writes results to a file | -## Interfaces +### Interfaces `Validation` exposes one public method: @@ -23,7 +23,7 @@ as its input parameter. |----------------|--------|------------------------------------------------------------| | `Run(context)` | Method | Execute all self-tests and optionally write a results file | -## Interactions +### Interactions | Unit / Subsystem | Role | |---------------------|-----------------------------------------------------------------------------| @@ -31,7 +31,7 @@ as its input parameter. | `MockRepoConnector` | Provides deterministic repository data for self-tests (RepoConnectors/Mock) | | `BuildInformation` | Generated during tests to verify report content | -## Validation Tests +### Validation Tests `Validation.Run` executes the following self-tests in order: @@ -43,7 +43,7 @@ as its input parameter. | `BuildMark_KnownIssuesReporting` | Known issues are correctly included in the report when requested | | `BuildMark_RulesRouting` | Rules-based item routing assigns items to the correct report sections | -## Error Handling +### Error Handling If `--results` is provided with an unsupported file extension (i.e., neither `.trx` nor `.xml`), `Validation.Run` writes an error message via `context.WriteError` and returns without writing a diff --git a/docs/design/build-mark/self-test/validation.md b/docs/design/build-mark/self-test/validation.md index 6ddc7dac..f6d88445 100644 --- a/docs/design/build-mark/self-test/validation.md +++ b/docs/design/build-mark/self-test/validation.md @@ -1,6 +1,6 @@ -# Validation +### Validation -## Overview +#### 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 @@ -9,20 +9,20 @@ optionally, to a TRX or JUnit XML results file. The unit is invoked by `Program.Run` when the `--validate` flag is set. -## Data Model +#### 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 +##### `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 +#### Methods -### `Run(Context context)` +##### `Run(Context context)` Entry point for self-validation. It: @@ -34,36 +34,36 @@ Entry point for self-validation. It: 5. Writes any unsupported extension as an error. 6. Sets `context.ExitCode` to `1` if any test fails. -### `RunMarkdownReportGeneration` +##### `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` +##### `RunGitIntegration` Uses `MockRepoConnector` to verify that the tool correctly extracts and displays version, commit hash, and previous version information from repository data. Validates the output against expected patterns. -### `RunIssueTracking` +##### `RunIssueTracking` Uses `MockRepoConnector` to verify that issues and pull requests are categorized and collected correctly into the `Changes` and `Bugs` lists of `BuildInformation`. -### `RunKnownIssuesReporting` +##### `RunKnownIssuesReporting` Uses `MockRepoConnector` to verify that known issues are included in the markdown report when the `--include-known-issues` flag is set. -### `RunRulesRouting` +##### `RunRulesRouting` Creates a `MockRepoConnector` configured with routing rules that direct items labelled `bug` to a `bugs` section and all other items to a `features` section. Generates a `BuildInformation` record, calls `ToMarkdown`, writes the output to a temporary file, and verifies the file contains both `## Features` and `## Bugs` section headings. -## Interactions +#### Interactions - `Context` provides output methods, `ResultsFile`, and the exit code sink. - `MockRepoConnector` supplies deterministic data for all tests in the diff --git a/docs/design/build-mark/utilities/utilities.md b/docs/design/build-mark/utilities.md similarity index 95% rename from docs/design/build-mark/utilities/utilities.md rename to docs/design/build-mark/utilities.md index 49734182..f339d2e7 100644 --- a/docs/design/build-mark/utilities/utilities.md +++ b/docs/design/build-mark/utilities.md @@ -1,6 +1,6 @@ -# Utilities Subsystem +## Utilities Subsystem -## Overview +### Overview The Utilities subsystem provides the shared helper classes used across the BuildMark system: @@ -11,14 +11,14 @@ BuildMark system: Version parsing, comparison, tag handling, and interval logic are implemented in the separate `Version` subsystem. -## Units +### Units | Unit | File | Responsibility | |-----------------|-----------------------------|----------------------------| | `PathHelpers` | `Utilities/PathHelpers.cs` | Safe path combination | | `ProcessRunner` | `Utilities/ProcessRunner.cs`| External process execution | -## Interfaces +### Interfaces `PathHelpers` exposes the following static method: @@ -33,7 +33,7 @@ the separate `Version` subsystem. | `RunAsync(command, params arguments)` | Method | Run a process and return stdout; throws on failure | | `TryRunAsync(command, params arguments)`| Method | Run a process and return stdout, or null on any failure | -## Interactions +### Interactions `PathHelpers` and `ProcessRunner` have no dependencies on other BuildMark subsystems. They are consumed by any unit that needs safe path combination or diff --git a/docs/design/build-mark/utilities/path-helpers.md b/docs/design/build-mark/utilities/path-helpers.md index 5f74555b..8a381aa7 100644 --- a/docs/design/build-mark/utilities/path-helpers.md +++ b/docs/design/build-mark/utilities/path-helpers.md @@ -1,6 +1,6 @@ -# PathHelpers Design +### PathHelpers Design -## Overview +#### Overview `PathHelpers` is a static utility class that provides a safe path-combination method. It protects callers against path-traversal attacks by verifying the resolved combined path stays @@ -8,9 +8,9 @@ within the base directory. Note that `Path.GetFullPath` normalizes `.`/`..` segm not resolve symlinks or reparse points, so this check guards against string-level traversal only. -## Class Structure +#### Class Structure -### SafePathCombine Method +##### SafePathCombine Method ```csharp internal static string SafePathCombine(string basePath, string relativePath) @@ -30,7 +30,7 @@ the base directory. or `Path.AltDirectorySeparatorChar`, or is itself rooted (absolute), which would indicate the combined path escapes the base directory. -## Design Decisions +#### Design Decisions - **`Path.GetRelativePath` for containment check**: Using `GetRelativePath` to verify containment handles root paths (e.g. `/`, `C:\`), platform case-sensitivity, and @@ -45,6 +45,6 @@ the base directory. - **No logging or error accumulation**: `SafePathCombine` is a pure utility method that throws on invalid input; it does not interact with the `Context` or any output mechanism. -## Interactions +#### Interactions `PathHelpers` has no dependencies on other BuildMark units or subsystems. diff --git a/docs/design/build-mark/utilities/process-runner.md b/docs/design/build-mark/utilities/process-runner.md index 9e5ab759..8ac2156a 100644 --- a/docs/design/build-mark/utilities/process-runner.md +++ b/docs/design/build-mark/utilities/process-runner.md @@ -1,15 +1,15 @@ -# ProcessRunner +### ProcessRunner -## Overview +#### Overview `ProcessRunner` is a static helper class in the Utilities subsystem that executes external shell commands and captures their standard output. It provides two public methods: `RunAsync`, which throws on failure, and `TryRunAsync`, which returns `null` on failure. -## Methods +#### Methods -### `RunAsync(command, params arguments) → string` +##### `RunAsync(command, params arguments) → string` Starts the specified process, captures stdout and stderr asynchronously, waits for exit, and returns the trimmed stdout string. Throws `InvalidOperationException` if @@ -20,7 +20,7 @@ The `arguments` parameter is a `params string[]` array. Each argument is added t the `ProcessStartInfo.ArgumentList` collection so that the Process class handles argument quoting correctly, rather than concatenating into a single string. -### `TryRunAsync(command, params arguments) → string?` +##### `TryRunAsync(command, params arguments) → string?` Executes the process and returns the stdout string if the exit code is zero, or `null` if the process fails or throws any exception. This method never propagates @@ -29,7 +29,7 @@ exceptions to its callers. The `arguments` parameter is a `params string[]` array, matching the signature of `RunAsync`. -### `CreateStartInfo(command, arguments) → ProcessStartInfo` +##### `CreateStartInfo(command, arguments) → ProcessStartInfo` Private helper method that creates a `ProcessStartInfo` for the given command. @@ -42,7 +42,7 @@ the command is invoked directly without a shell wrapper. Empty or whitespace-only commands are not routed through `cmd /c`, preserving the exception behavior for invalid commands. -## Interactions +#### Interactions | Unit / Subsystem | Role | |-------------------------------|------------------------------------------------------------------------| diff --git a/docs/design/build-mark/version/version.md b/docs/design/build-mark/version.md similarity index 89% rename from docs/design/build-mark/version/version.md rename to docs/design/build-mark/version.md index b204c4bd..1e997cad 100644 --- a/docs/design/build-mark/version/version.md +++ b/docs/design/build-mark/version.md @@ -1,12 +1,12 @@ -# Version Subsystem Design +## Version Subsystem Design -## Overview +### Overview The Version subsystem provides comprehensive semantic version processing capabilities for BuildMark. It encapsulates all version-related functionality including parsing, comparison, validation, and version range operations, ensuring consistent semantic versioning behavior across all BuildMark components. -## Architecture +### Architecture The Version subsystem is composed of six units: @@ -17,7 +17,7 @@ The Version subsystem is composed of six units: - `VersionIntervalSet` (Unit) - ordered collection of version intervals for range queries - `VersionCommitTag` (Unit) - version-to-commit association for build information -## Version Type Hierarchy +### Version Type Hierarchy ```text VersionTag (raw repository tag) @@ -31,19 +31,19 @@ VersionInterval / VersionIntervalSet (version ranges) VersionCommitTag (version + commit hash) ``` -## Design Principles +### Design Principles -### Semantic Versioning Compliance +#### Semantic Versioning Compliance All version processing strictly adheres to Semantic Versioning 2.0.0 () specification to ensure predictable and industry-standard behavior. -### Performance Optimization +#### Performance Optimization Version comparison operations are optimized for high-frequency usage in repository processing through construction-time parsing and cached segment arrays. -### Type Safety +#### Type Safety Each version type serves a specific purpose with clear boundaries: @@ -53,7 +53,7 @@ Each version type serves a specific purpose with clear boundaries: - **VersionInterval**: Range queries and filtering - **VersionCommitTag**: Build metadata association -## External Interfaces +### External Interfaces | Interface | Direction | Protocol / Format | |------------------|------------|-------------------------------------------| @@ -62,22 +62,22 @@ Each version type serves a specific purpose with clear boundaries: | Version Compare | Processing | IComparable standard interface | | Build Info | Output | VersionCommitTag records for build notes | -## Integration Points +### Integration Points -### Repository Connectors +#### Repository Connectors Version subsystem processes raw repository tags from GitHub and other sources, extracting semantic versions for build boundary determination. -### Build Notes +#### Build Notes Provides VersionCommitTag associations that link semantic versions to specific commit hashes for build information generation. -### Configuration +#### Configuration Supports version range specifications in configuration files through VersionInterval processing. -## Error Handling +### Error Handling Version processing provides two parsing patterns: @@ -86,15 +86,15 @@ Version processing provides two parsing patterns: - Malformed version ranges are rejected during parsing - Version comparison operations are guaranteed to be consistent and transitive -## Performance Characteristics +### Performance Characteristics -### Version Comparison +#### Version Comparison - **Construction**: O(n) where n is pre-release identifier count - **Comparison**: O(min(a,b)) where a,b are pre-release segment counts - **Memory**: Constant per-version overhead for parsed segments -### Version Range Operations +#### Version Range Operations - **Interval Creation**: O(1) for single ranges - **Set Operations**: O(n) where n is interval count diff --git a/docs/design/build-mark/version/version-commit-tag.md b/docs/design/build-mark/version/version-commit-tag.md index 721f12e0..ca1a9f55 100644 --- a/docs/design/build-mark/version/version-commit-tag.md +++ b/docs/design/build-mark/version/version-commit-tag.md @@ -1,13 +1,13 @@ -# VersionCommitTag +### VersionCommitTag -## Overview +#### Overview `VersionCommitTag` is a record in the Version subsystem that pairs a parsed `VersionTag` value with the Git commit hash at which that tag was created. It is used to identify the baseline and current version boundaries when assembling a `BuildInformation` record. -## Data Model +#### Data Model ```csharp public record VersionCommitTag( @@ -20,7 +20,7 @@ public record VersionCommitTag( | `VersionTag` | `VersionTag` | Parsed version information for this tag | | `CommitHash` | `string` | Git commit hash at the point this tag was made | -## Interactions +#### Interactions - `VersionTag` supplies the parsed tag and semantic version details. - `BuildInformation` uses `VersionCommitTag` for `BaselineVersionTag` and diff --git a/docs/design/build-mark/version/version-comparable.md b/docs/design/build-mark/version/version-comparable.md index b86a8ae0..57614cdd 100644 --- a/docs/design/build-mark/version/version-comparable.md +++ b/docs/design/build-mark/version/version-comparable.md @@ -1,12 +1,12 @@ -# Version Comparable +### Version Comparable -## Purpose +#### Purpose The `VersionComparable` class provides core semantic version comparison functionality. It handles versions in the format `major.minor.patch[-pre-release]` and implements proper semantic version ordering rules with optimized performance for pre-release comparison. -## Structure +#### Structure | Property | Type | Description | | -------- | ---- | ----------- | @@ -18,9 +18,9 @@ proper semantic version ordering rules with optimized performance for pre-releas | IsPreRelease | bool | Whether this is a pre-release version | | CompareVersion | string | Normalized comparison string (major.minor.patch[-pre-release]) | -## Performance Optimization +#### Performance Optimization -### Pre-Release Parsing +##### Pre-Release Parsing The class implements optimized pre-release comparison through: @@ -28,7 +28,7 @@ The class implements optimized pre-release comparison through: - **Construction-Time Parsing**: Pre-release strings are parsed once during object construction - **Efficient Comparison**: Comparisons use pre-parsed segments instead of repeated string operations -### Implementation Details +##### Implementation Details | Component | Description | | --------- | ----------- | @@ -39,7 +39,7 @@ The class implements optimized pre-release comparison through: This optimization eliminates repeated string splitting and parsing during comparison operations, providing significant performance benefits for sorting and version range operations. -## Interface +#### Interface The class implements `IComparable` providing analytical comparison: @@ -47,7 +47,7 @@ The class implements `IComparable` providing analytical compa - Release versions > pre-release versions for same numbers - SemVer-compliant pre-release ordering with numeric precedence -### Pre-Release Comparison Rules +##### Pre-Release Comparison Rules Pre-release versions follow SemVer specification: @@ -57,19 +57,19 @@ Pre-release versions follow SemVer specification: 3. Numeric identifiers have lower precedence than non-numeric 4. Shorter pre-release lists have lower precedence than longer ones -## Comparison Operators +#### Comparison Operators Standard comparison operators are overloaded: - `<`, `<=`, `>`, `>=` delegate to `CompareTo` - Natural ordering for use in collections and sorting -## Factory Methods +#### Factory Methods - `Create(string version)` - Creates instance, throws on invalid input - `TryCreate(string version)` - Returns null for invalid input -## Example +#### Example ```csharp var v1 = VersionComparable.Create("1.2.3"); @@ -81,7 +81,7 @@ var v5 = VersionComparable.Create("1.2.3-alpha.10"); // v4 < v5 < v2 < v1 < v3 (numeric pre-release comparison, pre-release < release) ``` -## Regex Pattern +#### Regex Pattern The class uses a generated regex pattern for parsing: diff --git a/docs/design/build-mark/version/version-interval-set.md b/docs/design/build-mark/version/version-interval-set.md index 2b5d2a68..8c64289c 100644 --- a/docs/design/build-mark/version/version-interval-set.md +++ b/docs/design/build-mark/version/version-interval-set.md @@ -1,4 +1,4 @@ -# VersionIntervalSet +### VersionIntervalSet The `VersionIntervalSet` unit is documented in `version-interval.md`, which covers both `VersionInterval` and `VersionIntervalSet` comprehensively, including the data model, parsing diff --git a/docs/design/build-mark/version/version-interval.md b/docs/design/build-mark/version/version-interval.md index 5bf433ea..b36c322e 100644 --- a/docs/design/build-mark/version/version-interval.md +++ b/docs/design/build-mark/version/version-interval.md @@ -1,6 +1,6 @@ -# VersionInterval and VersionIntervalSet +### VersionInterval and VersionIntervalSet -## Overview +#### Overview `VersionInterval` represents a single mathematical version interval using inclusive or exclusive bounds, where either bound may be omitted to indicate @@ -10,7 +10,7 @@ an ordered, immutable collection of one or more `VersionInterval` instances parsed from the `affected-versions` field of a `buildmark` block, and can test whether a version falls inside any contained interval. -## Interval Notation +#### Interval Notation The interval format follows standard mathematical notation: @@ -28,7 +28,7 @@ Multiple intervals are separated by `,` **between** ranges. The parser distinguishes a separating comma from the commas that appear **inside** an interval (between the bounds) by tracking bracket depth. -## Data Model - VersionInterval +#### Data Model - VersionInterval ```csharp public record VersionInterval( @@ -45,7 +45,7 @@ public record VersionInterval( | `UpperBound` | `string?` | Upper version string, or `null` if unbounded | | `UpperInclusive` | `bool` | `true` if the upper bound is inclusive (`]`) | -## Data Model - VersionIntervalSet +#### Data Model - VersionIntervalSet ```csharp public record VersionIntervalSet( @@ -56,9 +56,9 @@ public record VersionIntervalSet( |-------------|-----------------------------------|-----------------------------------| | `Intervals` | `IReadOnlyList` | Ordered list of parsed intervals | -## Methods +#### Methods -### `VersionInterval.Parse(string text) → VersionInterval?` +##### `VersionInterval.Parse(string text) → VersionInterval?` Parses a single interval token such as `(,1.0.1]` or `[1.1.0,1.2.0)`: @@ -70,7 +70,7 @@ Parses a single interval token such as `(,1.0.1]` or `[1.1.0,1.2.0)`: 5. Treat an empty string for either bound as `null` (unbounded). 6. Return `null` if the input does not match the expected pattern. -### `VersionIntervalSet.Parse(string text) → VersionIntervalSet` +##### `VersionIntervalSet.Parse(string text) → VersionIntervalSet` Parses a comma-separated list of intervals: @@ -82,7 +82,7 @@ Parses a comma-separated list of intervals: 4. Discard tokens that do not parse successfully. 5. Return a `VersionIntervalSet` wrapping the resulting list. -### `VersionInterval.Contains(string version) → bool` +##### `VersionInterval.Contains(string version) → bool` Tests whether a semantic version string falls within the interval: @@ -98,7 +98,7 @@ Tests whether a semantic version string falls within the interval: is `false`. 9. Return `true` otherwise. -### `VersionInterval.Contains(VersionComparable version) → bool` +##### `VersionInterval.Contains(VersionComparable version) → bool` Tests whether a `VersionComparable` instance falls within the interval: @@ -112,13 +112,13 @@ Tests whether a `VersionComparable` instance falls within the interval: is `false`. 7. Return `true` otherwise. -### `VersionInterval.Contains(VersionTag version) → bool` +##### `VersionInterval.Contains(VersionTag version) → bool` Convenience overload for callers that already hold a parsed BuildMark `VersionTag`. This overload delegates to `Contains(VersionComparable)` using `version.Semantic.Comparable`. -### `VersionIntervalSet.Contains(string version) → bool` +##### `VersionIntervalSet.Contains(string version) → bool` Tests whether a semantic version string falls within any interval in the set: @@ -127,7 +127,7 @@ Tests whether a semantic version string falls within any interval in the set: 3. Return `true` as soon as any interval contains the candidate version. 4. Return `false` when no interval matches. -### `VersionIntervalSet.Contains(VersionComparable version) → bool` +##### `VersionIntervalSet.Contains(VersionComparable version) → bool` Tests whether a `VersionComparable` instance falls within any interval in the set: @@ -136,13 +136,13 @@ Tests whether a `VersionComparable` instance falls within any interval in the se 3. Return `true` as soon as any interval contains the candidate version. 4. Return `false` when no interval matches. -### `VersionIntervalSet.Contains(VersionTag version) → bool` +##### `VersionIntervalSet.Contains(VersionTag version) → bool` Convenience overload for callers that already hold a parsed BuildMark `VersionTag`. This overload delegates to `Contains(VersionComparable)` using `version.Semantic.Comparable`. -## Parsing Examples +#### Parsing Examples | Input | Result | |----------------------------|---------------------------------------------------| @@ -151,7 +151,7 @@ Convenience overload for callers that already hold a parsed BuildMark | `(,1.0.1],[1.1.0,1.2.0)` | Two intervals | | `[3.0.0,)` | One interval: `3.0.0` and later | -## Interactions +#### Interactions `VersionInterval` and `VersionIntervalSet` are general-purpose utility types. They are created by `ItemControlsParser`, stored on `ItemControlsInfo`, and may diff --git a/docs/design/build-mark/version/version-semantic.md b/docs/design/build-mark/version/version-semantic.md index 5fb09463..8fe9531d 100644 --- a/docs/design/build-mark/version/version-semantic.md +++ b/docs/design/build-mark/version/version-semantic.md @@ -1,13 +1,13 @@ -# Version Semantic +### Version Semantic -## Purpose +#### Purpose The `VersionSemantic` record type extends `VersionComparable` with semantic version metadata support. As a C# `record`, it provides structural equality by default - two `VersionSemantic` instances are equal when all their properties compare equal. It provides the full semantic version structure including build metadata while preserving comparison functionality. -## Structure +#### Structure | Property | Type | Description | | -------- | ---- | ----------- | @@ -15,7 +15,7 @@ version structure including build metadata while preserving comparison functiona | Metadata | string? | Build metadata (+metadata), or `null` when absent | | FullVersion | string | Complete version string (major.minor.patch\[-pre-release\]\[+metadata\]) | -## Delegated Properties +#### Delegated Properties For convenience, the following properties delegate to the `Comparable` instance: @@ -25,17 +25,17 @@ For convenience, the following properties delegate to the `Comparable` instance: - `IsPreRelease` - Whether this is a pre-release version - `CompareVersion` - Comparison string (excludes metadata) -## Comparison +#### Comparison Comparison operations are performed on the `Comparable` instance, following semantic version rules where build metadata does not affect precedence. -## Factory Methods +#### Factory Methods - `Create(string version)` - Creates instance, throws on invalid input - `TryCreate(string version)` - Returns null for invalid input -### TryCreate Parsing Algorithm +##### TryCreate Parsing Algorithm 1. Return `null` if the input is null or whitespace. 2. Split on `+` using `Split('+', 2)` to separate the version string from optional build metadata. @@ -43,7 +43,7 @@ semantic version rules where build metadata does not affect precedence. 4. Delegate the version part to `VersionComparable.TryCreate`; return `null` if it returns `null`. 5. Return a new `VersionSemantic(comparable, metadata)`. -## Example +#### Example ```csharp var version = VersionSemantic.Create("1.2.3-beta.1+build.123"); diff --git a/docs/design/build-mark/version/version-tag.md b/docs/design/build-mark/version/version-tag.md index aa7dec8b..3a121029 100644 --- a/docs/design/build-mark/version/version-tag.md +++ b/docs/design/build-mark/version/version-tag.md @@ -1,6 +1,6 @@ -# Version Tag +### Version Tag -## Purpose +#### Purpose The `VersionTag` class parses repository tags to extract semantic version information. It handles various tag formats and prefixes while providing access to both the @@ -8,14 +8,14 @@ original tag and parsed semantic version. **Critically, VersionTag instances are compared based on their semantic version content (VersionComparable), not their tag strings, enabling version equality across different tag formats.** -## Structure +#### Structure | Property | Type | Description | |----------|-----------------|------------------------------| | Tag | string | Original repository tag | | Semantic | VersionSemantic | Parsed semantic version info | -## Delegated Properties +#### Delegated Properties For convenience, the following properties delegate to the `Semantic.Comparable` instance: @@ -29,7 +29,7 @@ Additional delegated properties from `Semantic`: - `Metadata` - Build metadata - `FullVersion` - Complete semantic version string -## Tag Format Support +#### Tag Format Support The parser supports various repository tag formats: @@ -39,7 +39,7 @@ The parser supports various repository tag formats: - Pre-release: `1.2.3-beta`, `1.2.3.rc.1` (dot becomes hyphen) - Metadata: `1.2.3+build.123` -## Version Equality +#### Version Equality **Important Design Principle**: VersionTag instances with different tag strings but identical semantic versions are considered equal. This enables repository connectors @@ -52,12 +52,12 @@ to correctly identify versions regardless of tagging conventions: This design prevents version matching failures when repositories use different tag naming conventions but identical semantic versions. -## Factory Methods +#### Factory Methods - `Create(string tag)` - Creates instance, throws on invalid tag - `TryCreate(string tag)` - Returns null for invalid tag -## Display / ToString +#### Display / ToString The `ToString()` method is overridden to return the original `Tag` string verbatim. This preserves the repository tag format for display and logging purposes while keeping semantic comparison @@ -69,7 +69,7 @@ Console.WriteLine(versionTag); // "release/1.2.3-rc.1" Console.WriteLine(versionTag.FullVersion); // "1.2.3-rc.1" ``` -## Example +#### Example ```csharp var versionTag = VersionTag.Create("MyApp-v1.2.3-beta.1+build.123"); diff --git a/docs/design/definition.yaml b/docs/design/definition.yaml index 23692c1c..e99ec16b 100644 --- a/docs/design/definition.yaml +++ b/docs/design/definition.yaml @@ -17,15 +17,15 @@ resource-path: input-files: - docs/design/title.txt - docs/design/introduction.md - - docs/design/build-mark/build-mark.md + - docs/design/build-mark.md - docs/design/build-mark/program.md - - docs/design/build-mark/build-notes/build-notes.md + - docs/design/build-mark/build-notes.md - docs/design/build-mark/build-notes/build-information.md - docs/design/build-mark/build-notes/item-info.md - docs/design/build-mark/build-notes/web-link.md - - docs/design/build-mark/cli/cli.md + - docs/design/build-mark/cli.md - docs/design/build-mark/cli/context.md - - docs/design/build-mark/configuration/configuration.md + - docs/design/build-mark/configuration.md - docs/design/build-mark/configuration/build-mark-config.md - docs/design/build-mark/configuration/build-mark-config-reader.md - docs/design/build-mark/configuration/configuration-load-result.md @@ -34,31 +34,31 @@ input-files: - docs/design/build-mark/configuration/report-config.md - docs/design/build-mark/configuration/rule-config.md - docs/design/build-mark/configuration/section-config.md - - docs/design/build-mark/self-test/self-test.md + - docs/design/build-mark/self-test.md - docs/design/build-mark/self-test/validation.md - - docs/design/build-mark/utilities/utilities.md + - docs/design/build-mark/utilities.md - docs/design/build-mark/utilities/path-helpers.md - docs/design/build-mark/utilities/process-runner.md - - docs/design/build-mark/version/version.md + - docs/design/build-mark/version.md - docs/design/build-mark/version/version-comparable.md - docs/design/build-mark/version/version-semantic.md - docs/design/build-mark/version/version-tag.md - docs/design/build-mark/version/version-interval.md - docs/design/build-mark/version/version-interval-set.md - docs/design/build-mark/version/version-commit-tag.md - - docs/design/build-mark/repo-connectors/repo-connectors.md + - docs/design/build-mark/repo-connectors.md - docs/design/build-mark/repo-connectors/repo-connector-base.md - docs/design/build-mark/repo-connectors/item-router.md - docs/design/build-mark/repo-connectors/item-controls-info.md - docs/design/build-mark/repo-connectors/item-controls-parser.md - docs/design/build-mark/repo-connectors/repo-connector-factory.md - - docs/design/build-mark/repo-connectors/github/github.md + - docs/design/build-mark/repo-connectors/github.md - docs/design/build-mark/repo-connectors/github/github-repo-connector.md - docs/design/build-mark/repo-connectors/github/github-graphql-client.md - docs/design/build-mark/repo-connectors/github/github-graphql-types.md - - docs/design/build-mark/repo-connectors/mock/mock.md + - docs/design/build-mark/repo-connectors/mock.md - docs/design/build-mark/repo-connectors/mock/mock-repo-connector.md - - docs/design/build-mark/repo-connectors/azure-devops/azure-devops.md + - docs/design/build-mark/repo-connectors/azure-devops.md - docs/design/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md - docs/design/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md - docs/design/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md diff --git a/docs/reqstream/build-mark/build-mark.yaml b/docs/reqstream/build-mark.yaml similarity index 100% rename from docs/reqstream/build-mark/build-mark.yaml rename to docs/reqstream/build-mark.yaml diff --git a/docs/reqstream/build-mark/build-notes/build-notes.yaml b/docs/reqstream/build-mark/build-notes.yaml similarity index 100% rename from docs/reqstream/build-mark/build-notes/build-notes.yaml rename to docs/reqstream/build-mark/build-notes.yaml diff --git a/docs/reqstream/build-mark/cli/cli.yaml b/docs/reqstream/build-mark/cli.yaml similarity index 100% rename from docs/reqstream/build-mark/cli/cli.yaml rename to docs/reqstream/build-mark/cli.yaml diff --git a/docs/reqstream/build-mark/configuration/configuration.yaml b/docs/reqstream/build-mark/configuration.yaml similarity index 100% rename from docs/reqstream/build-mark/configuration/configuration.yaml rename to docs/reqstream/build-mark/configuration.yaml diff --git a/docs/reqstream/build-mark/repo-connectors/repo-connectors.yaml b/docs/reqstream/build-mark/repo-connectors.yaml similarity index 100% rename from docs/reqstream/build-mark/repo-connectors/repo-connectors.yaml rename to docs/reqstream/build-mark/repo-connectors.yaml diff --git a/docs/reqstream/build-mark/repo-connectors/azure-devops/azure-devops.yaml b/docs/reqstream/build-mark/repo-connectors/azure-devops.yaml similarity index 100% rename from docs/reqstream/build-mark/repo-connectors/azure-devops/azure-devops.yaml rename to docs/reqstream/build-mark/repo-connectors/azure-devops.yaml diff --git a/docs/reqstream/build-mark/repo-connectors/github/github.yaml b/docs/reqstream/build-mark/repo-connectors/github.yaml similarity index 100% rename from docs/reqstream/build-mark/repo-connectors/github/github.yaml rename to docs/reqstream/build-mark/repo-connectors/github.yaml diff --git a/docs/reqstream/build-mark/repo-connectors/mock/mock.yaml b/docs/reqstream/build-mark/repo-connectors/mock.yaml similarity index 100% rename from docs/reqstream/build-mark/repo-connectors/mock/mock.yaml rename to docs/reqstream/build-mark/repo-connectors/mock.yaml diff --git a/docs/reqstream/build-mark/self-test/self-test.yaml b/docs/reqstream/build-mark/self-test.yaml similarity index 100% rename from docs/reqstream/build-mark/self-test/self-test.yaml rename to docs/reqstream/build-mark/self-test.yaml diff --git a/docs/reqstream/build-mark/utilities/utilities.yaml b/docs/reqstream/build-mark/utilities.yaml similarity index 100% rename from docs/reqstream/build-mark/utilities/utilities.yaml rename to docs/reqstream/build-mark/utilities.yaml diff --git a/docs/reqstream/build-mark/version/version.yaml b/docs/reqstream/build-mark/version.yaml similarity index 91% rename from docs/reqstream/build-mark/version/version.yaml rename to docs/reqstream/build-mark/version.yaml index 88aee7a3..831a1ffc 100644 --- a/docs/reqstream/build-mark/version/version.yaml +++ b/docs/reqstream/build-mark/version.yaml @@ -1,11 +1,11 @@ --- includes: - - version-comparable.yaml - - version-semantic.yaml - - version-tag.yaml - - version-interval.yaml - - version-interval-set.yaml - - version-commit-tag.yaml + - version/version-comparable.yaml + - version/version-semantic.yaml + - version/version-tag.yaml + - version/version-interval.yaml + - version/version-interval-set.yaml + - version/version-commit-tag.yaml sections: - title: Version Subsystem Requirements diff --git a/docs/verification/build-mark/build-mark.md b/docs/verification/build-mark.md similarity index 100% rename from docs/verification/build-mark/build-mark.md rename to docs/verification/build-mark.md diff --git a/docs/verification/build-mark/build-notes/build-notes.md b/docs/verification/build-mark/build-notes.md similarity index 87% rename from docs/verification/build-mark/build-notes/build-notes.md rename to docs/verification/build-mark/build-notes.md index 6ae40508..39e81173 100644 --- a/docs/verification/build-mark/build-notes/build-notes.md +++ b/docs/verification/build-mark/build-notes.md @@ -1,21 +1,21 @@ -# BuildNotes +## BuildNotes -## Verification Approach +### Verification Approach `BuildNotes` is the subsystem encompassing `BuildInformation`, `ItemInfo`, and `WebLink`. It is verified with dedicated subsystem tests in `BuildNotesTests.cs`. The subsystem uses `MockRepoConnector` to supply deterministic `BuildInformation` instances; no other mocking or test doubles are required. -## Dependencies +### Dependencies | Mock / Stub | Reason | | ------------------- | -------------------------------------------------------------------- | | `MockRepoConnector` | Provides deterministic `BuildInformation` for subsystem-level tests. | -## Test Scenarios +### Test Scenarios -### BuildNotes_ReportModel_GeneratesCorrectMarkdown +#### BuildNotes_ReportModel_GeneratesCorrectMarkdown **Scenario**: `MockRepoConnector.GetBuildInformationAsync` is called with version `v2.0.0`; the resulting `BuildInformation` is rendered via `ToMarkdown()`. @@ -25,7 +25,7 @@ resulting `BuildInformation` is rendered via `ToMarkdown()`. **Requirement coverage**: `BuildMark-BuildNotes-ReportModel`. -### BuildNotes_ReportModel_IncludesKnownIssues +#### BuildNotes_ReportModel_IncludesKnownIssues **Scenario**: `ToMarkdown(includeKnownIssues: true)` is called on a `BuildInformation` for `v2.0.0` that has known issues. @@ -35,7 +35,7 @@ that has known issues. **Requirement coverage**: `BuildMark-BuildNotes-ReportModel`. -### BuildNotes_ReportModel_IncludesFullChangelog +#### BuildNotes_ReportModel_IncludesFullChangelog **Scenario**: `ToMarkdown()` is called on a `BuildInformation` for `v2.0.0` that has a changelog link. @@ -45,7 +45,7 @@ link. **Requirement coverage**: `BuildMark-BuildNotes-ReportModel`. -## Requirements Coverage +### Requirements Coverage - **`BuildMark-BuildNotes-ReportModel`**: - BuildNotes_ReportModel_GeneratesCorrectMarkdown diff --git a/docs/verification/build-mark/build-notes/build-information.md b/docs/verification/build-mark/build-notes/build-information.md index bea51834..84892799 100644 --- a/docs/verification/build-mark/build-notes/build-information.md +++ b/docs/verification/build-mark/build-notes/build-information.md @@ -1,6 +1,6 @@ -# BuildInformation +### BuildInformation -## Verification Approach +#### Verification Approach `BuildInformation` is verified with dedicated unit tests in `BuildInformationTests.cs`. Tests construct `BuildInformation` instances either directly or via `MockRepoConnector`, invoke @@ -8,16 +8,16 @@ construct `BuildInformation` instances either directly or via `MockRepoConnector to simulate connector error conditions; `MockRepoConnector` is used for the remaining tests. No further mocking is needed. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | --- | --- | | `MockRepoConnector` | Supplies deterministic `BuildInformation` instances for rendering tests. | | `NSubstitute` (`IRepoConnector`) | Simulates error conditions that `MockRepoConnector` cannot reproduce. | -## Test Scenarios +#### Test Scenarios -### BuildInformation_GetBuildInformationAsync_ThrowsWhenNoVersionAndNoTags +##### BuildInformation_GetBuildInformationAsync_ThrowsWhenNoVersionAndNoTags **Scenario**: A substitute connector is configured to throw `InvalidOperationException` with the message "No tags found"; `GetBuildInformationAsync()` is called without a version argument. @@ -26,7 +26,7 @@ message "No tags found"; `GetBuildInformationAsync()` is called without a versio **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_GetBuildInformationAsync_ThrowsWhenNoVersionAndCommitDoesNotMatchTag +##### BuildInformation_GetBuildInformationAsync_ThrowsWhenNoVersionAndCommitDoesNotMatchTag **Scenario**: A substitute connector is configured to throw `InvalidOperationException` with the message "does not match any tag"; `GetBuildInformationAsync()` is called. @@ -35,7 +35,7 @@ message "does not match any tag"; `GetBuildInformationAsync()` is called. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_GetBuildInformationAsync_WorksWithExplicitVersion +##### BuildInformation_GetBuildInformationAsync_WorksWithExplicitVersion **Scenario**: `MockRepoConnector.GetBuildInformationAsync(VersionTag.Create("v2.1.0"))` is called. @@ -44,7 +44,7 @@ message "does not match any tag"; `GetBuildInformationAsync()` is called. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_GetBuildInformationAsync_WorksWhenCurrentCommitMatchesLatestTag +##### BuildInformation_GetBuildInformationAsync_WorksWhenCurrentCommitMatchesLatestTag **Scenario**: A substitute connector returns a `BuildInformation` where `CurrentVersionTag` is `v2.0.0`; `GetBuildInformationAsync()` is called. @@ -54,7 +54,7 @@ message "does not match any tag"; `GetBuildInformationAsync()` is called. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_GetBuildInformationAsync_PreReleaseUsesPreviousTag +##### BuildInformation_GetBuildInformationAsync_PreReleaseUsesPreviousTag **Scenario**: `MockRepoConnector.GetBuildInformationAsync(VersionTag.Create("v2.0.0-beta.1"))` is called. @@ -64,7 +64,7 @@ called. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_GetBuildInformationAsync_ReleaseSkipsPreReleases +##### BuildInformation_GetBuildInformationAsync_ReleaseSkipsPreReleases **Scenario**: `MockRepoConnector.GetBuildInformationAsync(VersionTag.Create("v2.0.0"))` is called. @@ -73,7 +73,7 @@ called. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_GetBuildInformationAsync_CollectsIssuesCorrectly +##### BuildInformation_GetBuildInformationAsync_CollectsIssuesCorrectly **Scenario**: `MockRepoConnector.GetBuildInformationAsync(VersionTag.Create("ver-1.1.0"))` is called. @@ -83,7 +83,7 @@ contains 2 items (ids `"4"` and `"6"`). **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_GetBuildInformationAsync_OrdersChangesByIndex +##### BuildInformation_GetBuildInformationAsync_OrdersChangesByIndex **Scenario**: `MockRepoConnector.GetBuildInformationAsync(VersionTag.Create("ver-1.1.0"))` is called. @@ -93,7 +93,7 @@ called. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_GetBuildInformationAsync_SeparatesBugAndChangeIssues +##### BuildInformation_GetBuildInformationAsync_SeparatesBugAndChangeIssues **Scenario**: `MockRepoConnector.GetBuildInformationAsync(VersionTag.Create("v2.0.0"))` is called. @@ -101,7 +101,7 @@ called. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_GetBuildInformationAsync_HandlesFirstReleaseCorrectly +##### BuildInformation_GetBuildInformationAsync_HandlesFirstReleaseCorrectly **Scenario**: `MockRepoConnector.GetBuildInformationAsync(VersionTag.Create("v1.0.0"))` is called. @@ -109,7 +109,7 @@ called. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_ToMarkdown_GeneratesCorrectMarkdownWithDefaults +##### BuildInformation_ToMarkdown_GeneratesCorrectMarkdownWithDefaults **Scenario**: `ToMarkdown()` is called on `BuildInformation` for `v2.0.0` without any optional arguments. @@ -119,7 +119,7 @@ arguments. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_ToMarkdown_IncludesKnownIssuesWhenRequested +##### BuildInformation_ToMarkdown_IncludesKnownIssuesWhenRequested **Scenario**: `ToMarkdown(includeKnownIssues: true)` is called on `BuildInformation` for `v2.0.0`. @@ -128,7 +128,7 @@ is absent. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_ToMarkdown_RespectsCustomHeadingDepth +##### BuildInformation_ToMarkdown_RespectsCustomHeadingDepth **Scenario**: `ToMarkdown(headingDepth: 3)` is called on `BuildInformation` for `v2.0.0`. @@ -137,7 +137,7 @@ is absent. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_ToMarkdown_DisplaysNAForEmptyChanges +##### BuildInformation_ToMarkdown_DisplaysNAForEmptyChanges **Scenario**: A `BuildInformation` with an empty `Changes` list is rendered via `ToMarkdown()`. @@ -145,7 +145,7 @@ is absent. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_ToMarkdown_DisplaysNAForEmptyBugs +##### BuildInformation_ToMarkdown_DisplaysNAForEmptyBugs **Scenario**: A `BuildInformation` with an empty `Bugs` list is rendered via `ToMarkdown()`. @@ -153,7 +153,7 @@ is absent. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_ToMarkdown_IncludesIssueLinks +##### BuildInformation_ToMarkdown_IncludesIssueLinks **Scenario**: `ToMarkdown()` is called on `BuildInformation` for `v2.0.0` which has items with GitHub URLs. @@ -164,7 +164,7 @@ GitHub URLs. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_ToMarkdown_HandlesFirstReleaseWithNA +##### BuildInformation_ToMarkdown_HandlesFirstReleaseWithNA **Scenario**: `ToMarkdown()` is called on `BuildInformation` for `v1.0.0` (no baseline). @@ -173,7 +173,7 @@ GitHub URLs. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_ToMarkdown_IncludesFullChangelogWhenLinkPresent +##### BuildInformation_ToMarkdown_IncludesFullChangelogWhenLinkPresent **Scenario**: `ToMarkdown()` is called on `BuildInformation` for `v2.0.0` which has a changelog link. @@ -183,7 +183,7 @@ URL containing `ver-1.1.0...v2.0.0`. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_ToMarkdown_ExcludesFullChangelogWhenNoBaseline +##### BuildInformation_ToMarkdown_ExcludesFullChangelogWhenNoBaseline **Scenario**: `ToMarkdown()` is called on `BuildInformation` for `v1.0.0` (no baseline version). @@ -191,7 +191,7 @@ URL containing `ver-1.1.0...v2.0.0`. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### BuildInformation_ToMarkdown_UsesBulletLists +##### BuildInformation_ToMarkdown_UsesBulletLists **Scenario**: `ToMarkdown(includeKnownIssues: true)` is called on `BuildInformation` for `v2.0.0`. @@ -200,7 +200,7 @@ markdown table notation (`| :-: | :---------- |`) is present in those sections. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### VersionCommitTag_Constructor_StoresVersionAndHash +##### VersionCommitTag_Constructor_StoresVersionAndHash **Scenario**: A `VersionCommitTag` is constructed with a `VersionTag` and a commit hash string. @@ -209,7 +209,7 @@ string. **Requirement coverage**: `BuildMark-BuildInformation-Markdown`. -### WebLink_Constructor_StoresTextAndUrl +##### WebLink_Constructor_StoresTextAndUrl **Scenario**: A `WebLink` is constructed with display text and a target URL. @@ -218,7 +218,7 @@ supplied URL. **Requirement coverage**: `BuildMark-WebLink-Record`. -### BuildInformation_ToMarkdown_WithRoutedSections_RendersCustomSections +##### BuildInformation_ToMarkdown_WithRoutedSections_RendersCustomSections **Scenario**: A `BuildInformation` is constructed with a populated `RoutedSections` list containing two custom sections (Features, Bugs); `ToMarkdown()` is called. @@ -228,7 +228,7 @@ two custom sections (Features, Bugs); `ToMarkdown()` is called. **Requirement coverage**: `BuildMark-BuildInformation-RoutedSections`. -### BuildInformation_ToMarkdown_WithoutRoutedSections_RendersDefaultSections +##### BuildInformation_ToMarkdown_WithoutRoutedSections_RendersDefaultSections **Scenario**: A `BuildInformation` is constructed with `RoutedSections` left as null; `ToMarkdown()` is called. @@ -237,7 +237,7 @@ two custom sections (Features, Bugs); `ToMarkdown()` is called. **Requirement coverage**: `BuildMark-BuildInformation-RoutedSections`. -## Requirements Coverage +#### Requirements Coverage - **`BuildMark-BuildInformation-Markdown`**: - BuildInformation_GetBuildInformationAsync_ThrowsWhenNoVersionAndNoTags diff --git a/docs/verification/build-mark/build-notes/item-info.md b/docs/verification/build-mark/build-notes/item-info.md index f19ad36d..2384558b 100644 --- a/docs/verification/build-mark/build-notes/item-info.md +++ b/docs/verification/build-mark/build-notes/item-info.md @@ -1,21 +1,21 @@ -# ItemInfo +### ItemInfo -## Verification Approach +#### Verification Approach `ItemInfo` is a record type that carries no logic of its own. It is verified through `BuildInformationTests.cs`, which asserts on the ordering, identity, and link properties of `ItemInfo` entries returned by `MockRepoConnector`. No mocking beyond `MockRepoConnector` is needed. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ------------------- | -------------------------------------------------------------------- | | `MockRepoConnector` | Provides `BuildInformation` instances with known `ItemInfo` entries. | -## Test Scenarios +#### Test Scenarios -### BuildInformation_GetBuildInformationAsync_OrdersChangesByIndex +##### BuildInformation_GetBuildInformationAsync_OrdersChangesByIndex **Scenario**: `MockRepoConnector.GetBuildInformationAsync(VersionTag.Create("ver-1.1.0"))` is called; the `Changes` collection is inspected. @@ -25,7 +25,7 @@ entry has `Index` 10 and `Id` `"1"`; the second has `Index` 13. **Requirement coverage**: `BuildMark-ItemInfo-Record`. -### BuildInformation_ToMarkdown_UsesBulletLists +##### BuildInformation_ToMarkdown_UsesBulletLists **Scenario**: `ToMarkdown(includeKnownIssues: true)` is called on `BuildInformation` for `v2.0.0`; the rendered bullet list items are inspected. @@ -35,7 +35,7 @@ present. **Requirement coverage**: `BuildMark-ItemInfo-Record`. -## Requirements Coverage +#### Requirements Coverage - **`BuildMark-ItemInfo-Record`**: - BuildInformation_GetBuildInformationAsync_OrdersChangesByIndex diff --git a/docs/verification/build-mark/build-notes/web-link.md b/docs/verification/build-mark/build-notes/web-link.md index 399cb2da..42b00e47 100644 --- a/docs/verification/build-mark/build-notes/web-link.md +++ b/docs/verification/build-mark/build-notes/web-link.md @@ -1,20 +1,20 @@ -# WebLink +### WebLink -## Verification Approach +#### Verification Approach `WebLink` is a record type with no logic. It is verified through a dedicated test in `BuildInformationTests.cs` that constructs a `WebLink` directly and asserts on its properties. No mocking is required. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | --------------- | | None | No mocks needed | -## Test Scenarios +#### Test Scenarios -### WebLink_Constructor_StoresTextAndUrl +##### WebLink_Constructor_StoresTextAndUrl **Scenario**: A `WebLink` is constructed with display text `"v1.0.0...v2.0.0"` and a GitHub compare URL. @@ -23,7 +23,7 @@ compare URL. **Requirement coverage**: `BuildMark-WebLink-Record`. -## Requirements Coverage +#### Requirements Coverage - **`BuildMark-WebLink-Record`**: - WebLink_Constructor_StoresTextAndUrl diff --git a/docs/verification/build-mark/cli/cli.md b/docs/verification/build-mark/cli.md similarity index 87% rename from docs/verification/build-mark/cli/cli.md rename to docs/verification/build-mark/cli.md index d84a3a9c..db51ad20 100644 --- a/docs/verification/build-mark/cli/cli.md +++ b/docs/verification/build-mark/cli.md @@ -1,6 +1,6 @@ -# Cli +## Cli -## Verification Approach +### Verification Approach The Cli subsystem is verified through `CliTests.cs`, which exercises the `Context` class directly by constructing instances with various argument combinations and @@ -8,16 +8,16 @@ asserting on the resulting property values. Each test targets a specific flag or argument combination and validates correct parsing behavior, including error conditions and output behavior. -## Dependencies +### Dependencies | Mock / Stub | Reason | | -------------------- | ------------------------------------------------------------------ | | `StringWriter` | Captures context output for assertion without console side effects | | In-process arguments | Passed directly to `Context` constructor instead of `args[]` | -## Test Scenarios +### Test Scenarios -### Cli_Context_EmptyArguments_CreatesValidContext +#### Cli_Context_EmptyArguments_CreatesValidContext **Scenario**: A `Context` is created with no arguments. @@ -25,7 +25,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Cli-Context` -### Cli_VersionFlag_SetsProperty +#### Cli_VersionFlag_SetsProperty **Scenario**: Context is created with `--version` argument. @@ -33,7 +33,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Program-Version` -### Cli_HelpFlag_SetsProperty +#### Cli_HelpFlag_SetsProperty **Scenario**: Context is created with `--help` argument. @@ -41,7 +41,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Program-Help` -### Cli_SilentFlag_SetsProperty +#### Cli_SilentFlag_SetsProperty **Scenario**: Context is created with `--silent` argument. @@ -49,7 +49,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Program-Silent` -### Cli_SilentFlag_SuppressesConsoleOutput +#### Cli_SilentFlag_SuppressesConsoleOutput **Scenario**: Context is created with `--silent` argument and a write is performed. @@ -57,7 +57,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Program-Silent` -### Cli_BuildVersionFlag_SetsProperty +#### Cli_BuildVersionFlag_SetsProperty **Scenario**: Context is created with `--build-version 1.2.3` argument. @@ -65,7 +65,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Program-BuildVersion` -### Cli_ReportFlags_SetProperties +#### Cli_ReportFlags_SetProperties **Scenario**: Context is created with `["--report", "output.md", "--depth", "3", "--include-known-issues"]`. @@ -74,7 +74,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Program-Report`, `BuildMark-Program-Depth` -### Cli_LogFlag_CreatesLogFile +#### Cli_LogFlag_CreatesLogFile **Scenario**: Context is created with `--log path.log` argument. @@ -82,7 +82,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Program-Log` -### Cli_ValidateFlag_SetsProperty +#### Cli_ValidateFlag_SetsProperty **Scenario**: Context is created with `--validate` argument. @@ -90,7 +90,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Program-Validate` -### Cli_ResultsFlag_SetsProperty +#### Cli_ResultsFlag_SetsProperty **Scenario**: Context is created with `["--results", "results.trx"]`. @@ -98,7 +98,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Program-Results` -### Cli_ResultFlag_SetsProperty +#### Cli_ResultFlag_SetsProperty **Scenario**: Context is created with `["--result", "results.trx"]` (alias). @@ -106,7 +106,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Program-Results` -### Cli_ErrorOutput_WritesToStderr +#### Cli_ErrorOutput_WritesToStderr **Scenario**: `context.WriteError` is called with an error message. @@ -114,7 +114,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Program-ErrorHandling` -### Cli_InvalidArgument_ThrowsException +#### Cli_InvalidArgument_ThrowsException **Scenario**: Context is created with `["--unsupported"]`. @@ -123,7 +123,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Cli-Context` -### Cli_MissingArgumentValue_ThrowsException +#### Cli_MissingArgumentValue_ThrowsException **Scenario**: Context is created with `["--build-version"]` (value missing). @@ -132,7 +132,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Cli-Context` -### Cli_ExitCode_DefaultsToZero +#### Cli_ExitCode_DefaultsToZero **Scenario**: Context is created; `ExitCode` property is read without any errors. @@ -140,7 +140,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Cli-Context` -### Cli_WriteError_SetsExitCodeToOne +#### Cli_WriteError_SetsExitCodeToOne **Scenario**: `context.WriteError` is called. @@ -148,7 +148,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Program-ErrorHandling` -### Cli_VersionShortFlag_SetsProperty +#### Cli_VersionShortFlag_SetsProperty **Scenario**: Context is created with `-v` short argument. @@ -156,7 +156,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Program-Version` -### Cli_HelpShortFlags_SetProperty +#### Cli_HelpShortFlags_SetProperty **Scenario**: Context is created with `-h` or `-?` short arguments. @@ -164,7 +164,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Program-Help` -### Cli_LintFlag_SetsProperty +#### Cli_LintFlag_SetsProperty **Scenario**: Context is created with `--lint` argument. @@ -172,7 +172,7 @@ and output behavior. **Requirement coverage**: `BuildMark-Program-Lint` -## Requirements Coverage +### Requirements Coverage - **BuildMark-Cli-Context**: Cli_Context_EmptyArguments_CreatesValidContext, Cli_InvalidArgument_ThrowsException, Cli_MissingArgumentValue_ThrowsException, diff --git a/docs/verification/build-mark/cli/context.md b/docs/verification/build-mark/cli/context.md index edeed440..a0df0c33 100644 --- a/docs/verification/build-mark/cli/context.md +++ b/docs/verification/build-mark/cli/context.md @@ -1,23 +1,23 @@ -# Context Verification +### Context Verification This document describes the unit-level verification design for the `Context` unit. It defines the test scenarios, dependency usage, and requirement coverage for `Cli/Context.cs`. -## Verification Approach +#### Verification Approach `Context` is verified with unit tests defined in `ContextTests.cs`. Because `Context` depends only on .NET base class library types (`Console`, `StreamWriter`, `Path`), no mocking or test doubles are required. Tests call `Context.Create` with controlled argument arrays, inspect the resulting properties and exit codes, and verify output written to captured streams. -## Dependencies +#### Dependencies `Context` has no dependencies on other tool units. All dependencies are real .NET BCL types; no mocking is needed at this level. -## Test Scenarios +#### Test Scenarios -### Context_Create_EmptyArguments_CreatesValidContext +##### Context_Create_EmptyArguments_CreatesValidContext **Scenario**: `Context.Create` is called with an empty argument array. @@ -26,7 +26,7 @@ exit code is 0. **Requirement coverage**: `BuildMark-Context-DefaultConstruction`. -### Context_Create_ShortVersionFlag_SetsVersionProperty +##### Context_Create_ShortVersionFlag_SetsVersionProperty **Scenario**: `Context.Create` is called with `["-v"]`. @@ -34,7 +34,7 @@ exit code is 0. **Requirement coverage**: `BuildMark-Context-FlagParsing`. -### Context_Create_LongVersionFlag_SetsVersionProperty +##### Context_Create_LongVersionFlag_SetsVersionProperty **Scenario**: `Context.Create` is called with `["--version"]`. @@ -42,7 +42,7 @@ exit code is 0. **Requirement coverage**: `BuildMark-Context-FlagParsing`. -### Context_Create_QuestionMarkHelpFlag_SetsHelpProperty +##### Context_Create_QuestionMarkHelpFlag_SetsHelpProperty **Scenario**: `Context.Create` is called with `["-?"]`. @@ -50,7 +50,7 @@ exit code is 0. **Requirement coverage**: `BuildMark-Context-FlagParsing`. -### Context_Create_ShortHelpFlag_SetsHelpProperty +##### Context_Create_ShortHelpFlag_SetsHelpProperty **Scenario**: `Context.Create` is called with `["-h"]`. @@ -58,7 +58,7 @@ exit code is 0. **Requirement coverage**: `BuildMark-Context-FlagParsing`. -### Context_Create_LongHelpFlag_SetsHelpProperty +##### Context_Create_LongHelpFlag_SetsHelpProperty **Scenario**: `Context.Create` is called with `["--help"]`. @@ -66,7 +66,7 @@ exit code is 0. **Requirement coverage**: `BuildMark-Context-FlagParsing`. -### Context_Create_SilentFlag_SetsSilentProperty +##### Context_Create_SilentFlag_SetsSilentProperty **Scenario**: `Context.Create` is called with `["--silent"]`. @@ -74,7 +74,7 @@ exit code is 0. **Requirement coverage**: `BuildMark-Context-FlagParsing`. -### Context_Create_ValidateFlag_SetsValidateProperty +##### Context_Create_ValidateFlag_SetsValidateProperty **Scenario**: `Context.Create` is called with `["--validate"]`. @@ -82,7 +82,7 @@ exit code is 0. **Requirement coverage**: `BuildMark-Context-FlagParsing`. -### Context_Create_LintFlag_SetsLintProperty +##### Context_Create_LintFlag_SetsLintProperty **Scenario**: `Context.Create` is called with `["--lint"]`. @@ -90,7 +90,7 @@ exit code is 0. **Requirement coverage**: `BuildMark-Context-FlagParsing`. -### Context_Create_BuildVersionArgument_SetsBuildVersionProperty +##### Context_Create_BuildVersionArgument_SetsBuildVersionProperty **Scenario**: `Context.Create` is called with `["--build-version", "1.2.3"]`. @@ -98,7 +98,7 @@ exit code is 0. **Requirement coverage**: `BuildMark-Context-ArgumentParsing`. -### Context_Create_ReportArgument_SetsReportFileProperty +##### Context_Create_ReportArgument_SetsReportFileProperty **Scenario**: `Context.Create` is called with `["--report", "output.md"]`. @@ -106,7 +106,7 @@ exit code is 0. **Requirement coverage**: `BuildMark-Context-ArgumentParsing`. -### Context_Create_DepthArgument_SetsDepthProperty +##### Context_Create_DepthArgument_SetsDepthProperty **Scenario**: `Context.Create` is called with `["--depth", "3"]`. @@ -114,7 +114,7 @@ exit code is 0. **Requirement coverage**: `BuildMark-Context-ArgumentParsing`. -### Context_Create_LegacyReportDepthArgument_SetsDepthProperty +##### Context_Create_LegacyReportDepthArgument_SetsDepthProperty **Scenario**: `Context.Create` is called with `["--report-depth", "3"]` (legacy alias for `--depth`). @@ -123,7 +123,7 @@ exit code is 0. **Requirement coverage**: `BuildMark-Context-ArgumentParsing`. -### Context_Create_IncludeKnownIssuesFlag_SetsIncludeKnownIssuesProperty +##### Context_Create_IncludeKnownIssuesFlag_SetsIncludeKnownIssuesProperty **Scenario**: `Context.Create` is called with `["--include-known-issues"]`. @@ -131,7 +131,7 @@ exit code is 0. **Requirement coverage**: `BuildMark-Context-FlagParsing`. -### Context_Create_ResultsArgument_SetsResultsFileProperty +##### Context_Create_ResultsArgument_SetsResultsFileProperty **Scenario**: `Context.Create` is called with `["--results", "output.trx"]`. @@ -139,7 +139,7 @@ exit code is 0. **Requirement coverage**: `BuildMark-Context-ArgumentParsing`. -### Context_Create_ResultArgument_SetsResultsFileProperty +##### Context_Create_ResultArgument_SetsResultsFileProperty **Scenario**: `Context.Create` is called with `["--result", "output.trx"]` (alias). @@ -147,7 +147,7 @@ exit code is 0. **Requirement coverage**: `BuildMark-Context-ArgumentParsing`. -### Context_Create_LogArgument_CreatesLogFile +##### Context_Create_LogArgument_CreatesLogFile **Scenario**: `Context.Create` is called with `["--log", ".log"]`; `WriteLine` is then called with a test message. @@ -156,7 +156,7 @@ with a test message. **Requirement coverage**: `BuildMark-Context-LogFile`. -### Context_Create_MultipleArguments_SetsAllPropertiesCorrectly +##### Context_Create_MultipleArguments_SetsAllPropertiesCorrectly **Scenario**: `Context.Create` is called with `["--silent", "--validate", "--lint", "--build-version", "1.2.3", "--report", "report.md", "--depth", "2", @@ -168,7 +168,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-FlagParsing`, `BuildMark-Context-ArgumentParsing`. -### Context_Create_UnsupportedArgument_ThrowsArgumentException +##### Context_Create_UnsupportedArgument_ThrowsArgumentException **Scenario**: `Context.Create` is called with `["--unsupported"]`. @@ -178,7 +178,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-ErrorHandling`. -### Context_Create_BuildVersionWithoutValue_ThrowsArgumentException +##### Context_Create_BuildVersionWithoutValue_ThrowsArgumentException **Scenario**: `Context.Create` is called with `["--build-version"]` (value missing). @@ -186,7 +186,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-ErrorHandling`. -### Context_Create_ReportWithoutValue_ThrowsArgumentException +##### Context_Create_ReportWithoutValue_ThrowsArgumentException **Scenario**: `Context.Create` is called with `["--report"]` (value missing). @@ -194,7 +194,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-ErrorHandling`. -### Context_Create_DepthWithoutValue_ThrowsArgumentException +##### Context_Create_DepthWithoutValue_ThrowsArgumentException **Scenario**: `Context.Create` is called with `["--depth"]` (value missing). @@ -202,7 +202,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-ErrorHandling`. -### Context_Create_DepthWithNonIntegerValue_ThrowsArgumentException +##### Context_Create_DepthWithNonIntegerValue_ThrowsArgumentException **Scenario**: `Context.Create` is called with `["--depth", "abc"]`. @@ -210,7 +210,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-ErrorHandling`. -### Context_Create_DepthWithZeroValue_ThrowsArgumentException +##### Context_Create_DepthWithZeroValue_ThrowsArgumentException **Scenario**: `Context.Create` is called with `["--depth", "0"]` (below minimum of 1). @@ -218,7 +218,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-ErrorHandling`. -### Context_Create_DepthWithNegativeValue_ThrowsArgumentException +##### Context_Create_DepthWithNegativeValue_ThrowsArgumentException **Scenario**: `Context.Create` is called with `["--depth", "-1"]` (negative value). @@ -226,7 +226,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-ErrorHandling`. -### Context_Create_DepthExceedingMaximum_ThrowsArgumentOutOfRangeException +##### Context_Create_DepthExceedingMaximum_ThrowsArgumentOutOfRangeException **Scenario**: `Context.Create` is called with `["--depth", "7"]` (above the maximum of 6). @@ -234,7 +234,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-ErrorHandling`. -### Context_Create_ResultsWithoutValue_ThrowsArgumentException +##### Context_Create_ResultsWithoutValue_ThrowsArgumentException **Scenario**: `Context.Create` is called with `["--results"]` (value missing). @@ -242,7 +242,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-ErrorHandling`. -### Context_Create_ResultWithoutValue_ThrowsArgumentException +##### Context_Create_ResultWithoutValue_ThrowsArgumentException **Scenario**: `Context.Create` is called with `["--result"]` (value missing). @@ -250,7 +250,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-ErrorHandling`. -### Context_Create_LogWithoutValue_ThrowsArgumentException +##### Context_Create_LogWithoutValue_ThrowsArgumentException **Scenario**: `Context.Create` is called with `["--log"]` (value missing). @@ -258,7 +258,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-ErrorHandling`. -### Context_Create_InvalidLogFilePath_ThrowsInvalidOperationException +##### Context_Create_InvalidLogFilePath_ThrowsInvalidOperationException **Scenario**: `Context.Create` is called with `["--log", ""]`. @@ -266,7 +266,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-ErrorHandling`. -### Context_WriteLine_NotSilent_WritesToConsole +##### Context_WriteLine_NotSilent_WritesToConsole **Scenario**: A non-silent `Context` is created and `WriteLine` is called with a test message. @@ -274,7 +274,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-Output`. -### Context_WriteLine_Silent_DoesNotWriteToConsole +##### Context_WriteLine_Silent_DoesNotWriteToConsole **Scenario**: A silent `Context` (created with `["--silent"]`) calls `WriteLine`. @@ -282,7 +282,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-SilentMode`. -### Context_WriteLine_WithLogFile_WritesToLogFile +##### Context_WriteLine_WithLogFile_WritesToLogFile **Scenario**: A `Context` created with a log file calls `WriteLine` with a test message. @@ -290,7 +290,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-LogFile`. -### Context_WriteError_NotSilent_WritesToConsole +##### Context_WriteError_NotSilent_WritesToConsole **Scenario**: A non-silent `Context` calls `WriteError` with a test message. @@ -298,7 +298,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-Output`. -### Context_WriteError_Silent_DoesNotWriteToConsole +##### Context_WriteError_Silent_DoesNotWriteToConsole **Scenario**: A silent `Context` calls `WriteError`. @@ -306,7 +306,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-SilentMode`. -### Context_WriteError_WithLogFile_WritesToLogFile +##### Context_WriteError_WithLogFile_WritesToLogFile **Scenario**: A `Context` created with a log file calls `WriteError` with a test message. @@ -314,7 +314,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-LogFile`. -### Context_WriteError_SetsExitCodeToOne +##### Context_WriteError_SetsExitCodeToOne **Scenario**: A `Context` calls `WriteError`. @@ -322,7 +322,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-ExitCode`. -### Context_ExitCode_NoErrors_RemainsZero +##### Context_ExitCode_NoErrors_RemainsZero **Scenario**: A `Context` is created and no errors are written. @@ -330,7 +330,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-ExitCode`. -### Context_Dispose_ClosesLogFileProperly +##### Context_Dispose_ClosesLogFileProperly **Scenario**: A `Context` with a log file is disposed. @@ -338,7 +338,7 @@ equals `"1.2.3"`; `ReportFile` equals `"report.md"`; `Depth` equals 2; `ResultsF **Requirement coverage**: `BuildMark-Context-LogFile`. -## Requirements Coverage +#### Requirements Coverage - **`BuildMark-Context-DefaultConstruction`**: - Context_Create_EmptyArguments_CreatesValidContext diff --git a/docs/verification/build-mark/configuration/configuration.md b/docs/verification/build-mark/configuration.md similarity index 86% rename from docs/verification/build-mark/configuration/configuration.md rename to docs/verification/build-mark/configuration.md index d8673c2d..b0b66875 100644 --- a/docs/verification/build-mark/configuration/configuration.md +++ b/docs/verification/build-mark/configuration.md @@ -1,21 +1,21 @@ -# Configuration +## Configuration -## Verification Approach +### Verification Approach The Configuration subsystem is verified with dedicated subsystem tests in `ConfigurationSubsystemTests.cs`. Tests create temporary `.buildmark.yaml` files, call `BuildMarkConfigReader.ReadAsync`, and assert on the returned `ConfigurationLoadResult`. No mocking is required; the real file system is used with temporary directories. -## Dependencies +### Dependencies | Mock / Stub | Reason | | ----------- | -------------------------------------------------------------------- | | File system | Tests create temporary `.buildmark.yaml` files in `Path.GetTempPath` | -## Test Scenarios +### Test Scenarios -### Configuration_ReadAsync_ValidFile_ReturnsConfiguration +#### Configuration_ReadAsync_ValidFile_ReturnsConfiguration **Scenario**: A valid `.buildmark.yaml` containing a GitHub connector, one section, and one rule is written to a temp directory; `BuildMarkConfigReader.ReadAsync` is called. @@ -25,7 +25,7 @@ is written to a temp directory; `BuildMarkConfigReader.ReadAsync` is called. **Requirement coverage**: `BuildMark-Configuration-Read`. -### Configuration_ReadAsync_MissingFile_ReturnsEmptyResult +#### Configuration_ReadAsync_MissingFile_ReturnsEmptyResult **Scenario**: `BuildMarkConfigReader.ReadAsync` is called on a temp directory containing no `.buildmark.yaml`. @@ -34,7 +34,7 @@ is written to a temp directory; `BuildMarkConfigReader.ReadAsync` is called. **Requirement coverage**: `BuildMark-Configuration-Read`. -### Configuration_ReadAsync_MalformedFile_ReportsError +#### Configuration_ReadAsync_MalformedFile_ReportsError **Scenario**: A `.buildmark.yaml` with a tab character (malformed YAML) is written; `BuildMarkConfigReader.ReadAsync` is called. @@ -44,7 +44,7 @@ is written to a temp directory; `BuildMarkConfigReader.ReadAsync` is called. **Requirement coverage**: `BuildMark-Configuration-Read`. -### Configuration_Issues_ErrorIssue_SetsExitCode +#### Configuration_Issues_ErrorIssue_SetsExitCode **Scenario**: A `ConfigurationLoadResult` containing one `Error`-severity `ConfigurationIssue` is created; `ReportTo(context)` is called on a silent context. @@ -53,7 +53,7 @@ created; `ReportTo(context)` is called on a silent context. **Requirement coverage**: `BuildMark-Configuration-Issues`. -### Configuration_Issues_WarningIssue_DoesNotSetExitCode +#### Configuration_Issues_WarningIssue_DoesNotSetExitCode **Scenario**: A `ConfigurationLoadResult` containing one `Warning`-severity `ConfigurationIssue` is created; `ReportTo(context)` is called on a silent context. @@ -62,7 +62,7 @@ is created; `ReportTo(context)` is called on a silent context. **Requirement coverage**: `BuildMark-Configuration-Issues`. -### Configuration_Issues_ValidationError_ReportsAccurateLine +#### Configuration_Issues_ValidationError_ReportsAccurateLine **Scenario**: A `.buildmark.yaml` with an unsupported key on line 3 is written; `BuildMarkConfigReader.ReadAsync` is called. @@ -71,7 +71,7 @@ is created; `ReportTo(context)` is called on a silent context. **Requirement coverage**: `BuildMark-Configuration-Issues`. -### Configuration_ConnectorConfig_ValidFile_ParsesConnectorSettings +#### Configuration_ConnectorConfig_ValidFile_ParsesConnectorSettings **Scenario**: A `.buildmark.yaml` with a GitHub connector block (owner, repo, base-url) is written; `BuildMarkConfigReader.ReadAsync` is called. @@ -81,7 +81,7 @@ written; `BuildMarkConfigReader.ReadAsync` is called. **Requirement coverage**: `BuildMark-Configuration-ConnectorConfig`. -### Configuration_ConnectorConfig_ValidFile_ParsesAzureDevOpsSettings +#### Configuration_ConnectorConfig_ValidFile_ParsesAzureDevOpsSettings **Scenario**: A `.buildmark.yaml` with an Azure DevOps connector block (url, organization, project, repository) is written; `BuildMarkConfigReader.ReadAsync` is called. @@ -92,7 +92,7 @@ values. **Requirement coverage**: `BuildMark-Configuration-ConnectorConfig`. -## Requirements Coverage +### Requirements Coverage - **`BuildMark-Configuration-Read`**: - Configuration_ReadAsync_ValidFile_ReturnsConfiguration diff --git a/docs/verification/build-mark/configuration/azure-dev-ops-connector-config.md b/docs/verification/build-mark/configuration/azure-devops-connector-config.md similarity index 86% rename from docs/verification/build-mark/configuration/azure-dev-ops-connector-config.md rename to docs/verification/build-mark/configuration/azure-devops-connector-config.md index 941c8893..1c82fd52 100644 --- a/docs/verification/build-mark/configuration/azure-dev-ops-connector-config.md +++ b/docs/verification/build-mark/configuration/azure-devops-connector-config.md @@ -1,21 +1,21 @@ -# AzureDevOpsConnectorConfig +### AzureDevOpsConnectorConfig -## Verification Approach +#### Verification Approach `AzureDevOpsConnectorConfig` is verified through `ConfigurationTests.cs`. Tests write `.buildmark.yaml` files with Azure DevOps connector blocks and assert that `OrganizationUrl`, `Organization`, `Project`, and `Repository` properties are correctly parsed, including alias key support. No mocking is required. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | -------------------------------------------------------------------- | | File system | Tests create temporary `.buildmark.yaml` files in `Path.GetTempPath` | -## Test Scenarios +#### Test Scenarios -### BuildMarkConfigReader_ReadAsync_ValidAzureDevOpsConnector_ReturnsParsedConfiguration +##### BuildMarkConfigReader_ReadAsync_ValidAzureDevOpsConnector_ReturnsParsedConfiguration **Scenario**: A `.buildmark.yaml` with an Azure DevOps connector block using canonical keys (`organization`, `repository`) is written; `BuildMarkConfigReader.ReadAsync` is called; @@ -26,7 +26,7 @@ support. No mocking is required. **Requirement coverage**: `BuildMark-AzureDevOpsConnectorConfig-Properties`. -### BuildMarkConfigReader_ReadAsync_AzureDevOpsConnectorAliases_ReturnsParsedConfiguration +##### BuildMarkConfigReader_ReadAsync_AzureDevOpsConnectorAliases_ReturnsParsedConfiguration **Scenario**: A `.buildmark.yaml` with Azure DevOps connector using alias keys (`org`, `repo`) is written; `BuildMarkConfigReader.ReadAsync` is called; `Config.Connector.AzureDevOps` is inspected. @@ -36,7 +36,7 @@ correctly from the alias keys. **Requirement coverage**: `BuildMark-AzureDevOpsConnectorConfig-Properties`. -## Requirements Coverage +#### Requirements Coverage - **`BuildMark-AzureDevOpsConnectorConfig-Properties`**: - BuildMarkConfigReader_ReadAsync_ValidAzureDevOpsConnector_ReturnsParsedConfiguration diff --git a/docs/verification/build-mark/configuration/build-mark-config-reader.md b/docs/verification/build-mark/configuration/build-mark-config-reader.md index 3af72efd..e8ad5b00 100644 --- a/docs/verification/build-mark/configuration/build-mark-config-reader.md +++ b/docs/verification/build-mark/configuration/build-mark-config-reader.md @@ -1,21 +1,21 @@ -# BuildMarkConfigReader +### BuildMarkConfigReader -## Verification Approach +#### Verification Approach `BuildMarkConfigReader` is verified with dedicated unit tests in `ConfigurationTests.cs`. Tests write `.buildmark.yaml` files to temporary directories and call `BuildMarkConfigReader.ReadAsync`, asserting on the returned `ConfigurationLoadResult`. No mocking is required; the real file system is used. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | -------------------------------------------------------------------- | | File system | Tests create temporary `.buildmark.yaml` files in `Path.GetTempPath` | -## Test Scenarios +#### Test Scenarios -### BuildMarkConfigReader_ReadAsync_MissingFile_ReturnsEmptyResult +##### BuildMarkConfigReader_ReadAsync_MissingFile_ReturnsEmptyResult **Scenario**: `BuildMarkConfigReader.ReadAsync` is called on a temp directory containing no `.buildmark.yaml`. @@ -24,7 +24,7 @@ is used. **Requirement coverage**: `BuildMark-ConfigReader-MissingFile`. -### BuildMarkConfigReader_ReadAsync_ValidFile_ReturnsParsedConfiguration +##### BuildMarkConfigReader_ReadAsync_ValidFile_ReturnsParsedConfiguration **Scenario**: A `.buildmark.yaml` with a GitHub connector, sections, and rules is written; `BuildMarkConfigReader.ReadAsync` is called. @@ -34,7 +34,7 @@ sections, and rules are parsed correctly. **Requirement coverage**: `BuildMark-ConfigReader-ReadAsync`. -### BuildMarkConfigReader_ReadAsync_InvalidRepositoryValue_ReturnsErrorIssue +##### BuildMarkConfigReader_ReadAsync_InvalidRepositoryValue_ReturnsErrorIssue **Scenario**: A `.buildmark.yaml` with `repository: invalid` (not in `owner/repo` format) is written; `BuildMarkConfigReader.ReadAsync` is called. @@ -43,7 +43,7 @@ written; `BuildMarkConfigReader.ReadAsync` is called. **Requirement coverage**: `BuildMark-ConfigReader-MalformedFile`. -### BuildMarkConfigReader_ReadAsync_MalformedFile_ReturnsErrorIssue +##### BuildMarkConfigReader_ReadAsync_MalformedFile_ReturnsErrorIssue **Scenario**: A `.buildmark.yaml` containing a tab character (invalid YAML) is written; `BuildMarkConfigReader.ReadAsync` is called. @@ -53,7 +53,7 @@ written; `BuildMarkConfigReader.ReadAsync` is called. **Requirement coverage**: `BuildMark-ConfigReader-MalformedFile`. -### BuildMarkConfigReader_ReadAsync_ValidAzureDevOpsConnector_ReturnsParsedConfiguration +##### BuildMarkConfigReader_ReadAsync_ValidAzureDevOpsConnector_ReturnsParsedConfiguration **Scenario**: A `.buildmark.yaml` with an Azure DevOps connector block (url, organization, project, repository) is written; `BuildMarkConfigReader.ReadAsync` is called. @@ -63,7 +63,7 @@ correctly. **Requirement coverage**: `BuildMark-ConfigReader-ReadAsync`. -### BuildMarkConfigReader_ReadAsync_AzureDevOpsConnectorAliases_ReturnsParsedConfiguration +##### BuildMarkConfigReader_ReadAsync_AzureDevOpsConnectorAliases_ReturnsParsedConfiguration **Scenario**: A `.buildmark.yaml` with Azure DevOps connector using alias keys (`org`, `repo`) is written; `BuildMarkConfigReader.ReadAsync` is called. @@ -72,7 +72,7 @@ written; `BuildMarkConfigReader.ReadAsync` is called. **Requirement coverage**: `BuildMark-ConfigReader-ReadAsync`. -### BuildMarkConfigReader_ReadAsync_AzureDevOpsUnsupportedKey_ReturnsErrorIssue +##### BuildMarkConfigReader_ReadAsync_AzureDevOpsUnsupportedKey_ReturnsErrorIssue **Scenario**: A `.buildmark.yaml` with an unknown key inside the Azure DevOps connector block is written; `BuildMarkConfigReader.ReadAsync` is called. @@ -82,7 +82,7 @@ written; `BuildMarkConfigReader.ReadAsync` is called. **Requirement coverage**: `BuildMark-ConfigReader-MalformedFile`. -### BuildMarkConfigReader_ReadAsync_AzureDevOpsNonMapping_ReturnsErrorIssue +##### BuildMarkConfigReader_ReadAsync_AzureDevOpsNonMapping_ReturnsErrorIssue **Scenario**: A `.buildmark.yaml` where `azure-devops:` is a scalar value instead of a mapping is written; `BuildMarkConfigReader.ReadAsync` is called. @@ -91,7 +91,7 @@ written; `BuildMarkConfigReader.ReadAsync` is called. **Requirement coverage**: `BuildMark-ConfigReader-MalformedFile`. -## Requirements Coverage +#### Requirements Coverage - **`BuildMark-ConfigReader-ReadAsync`**: - BuildMarkConfigReader_ReadAsync_ValidFile_ReturnsParsedConfiguration diff --git a/docs/verification/build-mark/configuration/build-mark-config.md b/docs/verification/build-mark/configuration/build-mark-config.md index f0f30c72..ec9c98b4 100644 --- a/docs/verification/build-mark/configuration/build-mark-config.md +++ b/docs/verification/build-mark/configuration/build-mark-config.md @@ -1,21 +1,21 @@ -# BuildMarkConfig +### BuildMarkConfig -## Verification Approach +#### Verification Approach `BuildMarkConfig` is verified with dedicated unit tests in `ConfigurationTests.cs`. The test `BuildMarkConfig_CreateDefault_ContainsDependencyUpdatesSection` calls `BuildMarkConfig.CreateDefault()` and asserts on the returned sections and routing rules. No mocking is required. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | --------------- | | None | No mocks needed | -## Test Scenarios +#### Test Scenarios -### BuildMarkConfig_CreateDefault_ContainsDependencyUpdatesSection +##### BuildMarkConfig_CreateDefault_ContainsDependencyUpdatesSection **Scenario**: `BuildMarkConfig.CreateDefault()` is called. @@ -26,7 +26,7 @@ rule has a null match. **Requirement coverage**: `BuildMark-SectionConfig-Properties`, `BuildMark-RuleConfig-Properties`. -## Requirements Coverage +#### Requirements Coverage - **`BuildMark-SectionConfig-Properties`**: - BuildMarkConfig_CreateDefault_ContainsDependencyUpdatesSection diff --git a/docs/verification/build-mark/configuration/configuration-issue.md b/docs/verification/build-mark/configuration/configuration-issue.md index 30b234f0..8ef9d0ec 100644 --- a/docs/verification/build-mark/configuration/configuration-issue.md +++ b/docs/verification/build-mark/configuration/configuration-issue.md @@ -1,20 +1,20 @@ -# ConfigurationIssue +### ConfigurationIssue -## Verification Approach +#### Verification Approach `ConfigurationIssue` is a record type with no logic. It is verified through `ConfigurationTests.cs`, which constructs `ConfigurationIssue` instances directly and asserts on their `FilePath`, `Line`, `Severity`, and `Description` properties. No mocking is required. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | --------------- | | None | No mocks needed | -## Test Scenarios +#### Test Scenarios -### ConfigurationLoadResult_ReportTo_ErrorIssue_SetsExitCode +##### ConfigurationLoadResult_ReportTo_ErrorIssue_SetsExitCode **Scenario**: A `ConfigurationIssue` with `Error` severity is constructed and placed in a `ConfigurationLoadResult`; `ReportTo` is called. @@ -23,7 +23,7 @@ their `FilePath`, `Line`, `Severity`, and `Description` properties. No mocking i **Requirement coverage**: `BuildMark-ConfigurationIssue-Record`. -### ConfigurationLoadResult_ReportTo_WarningIssue_DoesNotSetExitCode +##### ConfigurationLoadResult_ReportTo_WarningIssue_DoesNotSetExitCode **Scenario**: A `ConfigurationIssue` with `Warning` severity is constructed and placed in a `ConfigurationLoadResult`; `ReportTo` is called. @@ -33,7 +33,7 @@ correctly. **Requirement coverage**: `BuildMark-ConfigurationIssue-Record`. -### ConfigurationLoadResult_ReportTo_IssueMessage_IncludesLineNumber +##### ConfigurationLoadResult_ReportTo_IssueMessage_IncludesLineNumber **Scenario**: A `ConfigurationIssue` is constructed with `FilePath` `"/repo/.buildmark.yaml"`, `Line` 7, `Error` severity, and description `"Unexpected value"`; properties are inspected. @@ -43,7 +43,7 @@ correctly. **Requirement coverage**: `BuildMark-ConfigurationIssue-Record`. -## Requirements Coverage +#### Requirements Coverage - **`BuildMark-ConfigurationIssue-Record`**: - ConfigurationLoadResult_ReportTo_ErrorIssue_SetsExitCode diff --git a/docs/verification/build-mark/configuration/configuration-load-result.md b/docs/verification/build-mark/configuration/configuration-load-result.md index 688b1a96..c22d845b 100644 --- a/docs/verification/build-mark/configuration/configuration-load-result.md +++ b/docs/verification/build-mark/configuration/configuration-load-result.md @@ -1,20 +1,20 @@ -# ConfigurationLoadResult +### ConfigurationLoadResult -## Verification Approach +#### Verification Approach `ConfigurationLoadResult` is verified with dedicated unit tests in `ConfigurationTests.cs`. Tests construct `ConfigurationLoadResult` instances directly with controlled `ConfigurationIssue` entries and assert on the behavior of `ReportTo(context)`. No mocking is required. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | --------------- | | None | No mocks needed | -## Test Scenarios +#### Test Scenarios -### ConfigurationLoadResult_ReportTo_ErrorIssue_SetsExitCode +##### ConfigurationLoadResult_ReportTo_ErrorIssue_SetsExitCode **Scenario**: A `ConfigurationLoadResult` containing one `Error`-severity issue is created; `ReportTo` is called on a silent `Context`. @@ -23,7 +23,7 @@ and assert on the behavior of `ReportTo(context)`. No mocking is required. **Requirement coverage**: `BuildMark-ConfigLoadResult-ReportTo`. -### ConfigurationLoadResult_ReportTo_WarningIssue_DoesNotSetExitCode +##### ConfigurationLoadResult_ReportTo_WarningIssue_DoesNotSetExitCode **Scenario**: A `ConfigurationLoadResult` containing one `Warning`-severity issue is created; `ReportTo` is called on a silent `Context`. @@ -32,7 +32,7 @@ and assert on the behavior of `ReportTo(context)`. No mocking is required. **Requirement coverage**: `BuildMark-ConfigLoadResult-ReportTo`. -### ConfigurationLoadResult_ReportTo_IssueMessage_IncludesLineNumber +##### ConfigurationLoadResult_ReportTo_IssueMessage_IncludesLineNumber **Scenario**: A `ConfigurationLoadResult` containing an `Error`-severity issue at `FilePath` `"/repo/.buildmark.yaml"`, `Line` 7, with description `"Unexpected value"` is created; `ReportTo` @@ -44,7 +44,7 @@ is called. **Requirement coverage**: `BuildMark-ConfigLoadResult-ReportTo`. -## Requirements Coverage +#### Requirements Coverage - **`BuildMark-ConfigLoadResult-ReportTo`**: - ConfigurationLoadResult_ReportTo_ErrorIssue_SetsExitCode diff --git a/docs/verification/build-mark/configuration/connector-config.md b/docs/verification/build-mark/configuration/connector-config.md index aa0953db..23419d67 100644 --- a/docs/verification/build-mark/configuration/connector-config.md +++ b/docs/verification/build-mark/configuration/connector-config.md @@ -1,21 +1,21 @@ -# ConnectorConfig +### ConnectorConfig -## Verification Approach +#### Verification Approach `ConnectorConfig` is verified through `ConfigurationTests.cs`. Tests write `.buildmark.yaml` files with connector blocks and assert that `ConnectorConfig.Type`, `ConnectorConfig.GitHub`, and `ConnectorConfig.AzureDevOps` are correctly populated by `BuildMarkConfigReader.ReadAsync`. No mocking is required. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | -------------------------------------------------------------------- | | File system | Tests create temporary `.buildmark.yaml` files in `Path.GetTempPath` | -## Test Scenarios +#### Test Scenarios -### BuildMarkConfigReader_ReadAsync_ValidFile_ReturnsParsedConfiguration +##### BuildMarkConfigReader_ReadAsync_ValidFile_ReturnsParsedConfiguration **Scenario**: A `.buildmark.yaml` with a GitHub connector block is written; `BuildMarkConfigReader.ReadAsync` is called; `Config.Connector` is inspected. @@ -25,7 +25,7 @@ mocking is required. **Requirement coverage**: `BuildMark-ConnectorConfig-Properties`. -### BuildMarkConfigReader_ReadAsync_ValidAzureDevOpsConnector_ReturnsParsedConfiguration +##### BuildMarkConfigReader_ReadAsync_ValidAzureDevOpsConnector_ReturnsParsedConfiguration **Scenario**: A `.buildmark.yaml` with an Azure DevOps connector block is written; `BuildMarkConfigReader.ReadAsync` is called; `Config.Connector` is inspected. @@ -35,7 +35,7 @@ mocking is required. **Requirement coverage**: `BuildMark-ConnectorConfig-Properties`. -## Requirements Coverage +#### Requirements Coverage - **`BuildMark-ConnectorConfig-Properties`**: - BuildMarkConfigReader_ReadAsync_ValidFile_ReturnsParsedConfiguration diff --git a/docs/verification/build-mark/configuration/git-hub-connector-config.md b/docs/verification/build-mark/configuration/git-hub-connector-config.md index 36af5976..32c2cf0b 100644 --- a/docs/verification/build-mark/configuration/git-hub-connector-config.md +++ b/docs/verification/build-mark/configuration/git-hub-connector-config.md @@ -1,20 +1,20 @@ -# GitHubConnectorConfig +### GitHubConnectorConfig -## Verification Approach +#### Verification Approach `GitHubConnectorConfig` is verified through `ConfigurationTests.cs`. Tests write `.buildmark.yaml` files with a GitHub connector block and assert that `Owner`, `Repo`, and `BaseUrl` properties are correctly parsed. No mocking is required. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | -------------------------------------------------------------------- | | File system | Tests create temporary `.buildmark.yaml` files in `Path.GetTempPath` | -## Test Scenarios +#### Test Scenarios -### BuildMarkConfigReader_ReadAsync_ValidFile_ReturnsParsedConfiguration +##### BuildMarkConfigReader_ReadAsync_ValidFile_ReturnsParsedConfiguration **Scenario**: A `.buildmark.yaml` with `github.owner`, `github.repo`, and `github.base-url` fields is written; `BuildMarkConfigReader.ReadAsync` is called; `Config.Connector.GitHub` is inspected. @@ -24,7 +24,7 @@ is written; `BuildMarkConfigReader.ReadAsync` is called; `Config.Connector.GitHu **Requirement coverage**: `BuildMark-GitHubConnectorConfig-Properties`. -## Requirements Coverage +#### Requirements Coverage - **`BuildMark-GitHubConnectorConfig-Properties`**: - BuildMarkConfigReader_ReadAsync_ValidFile_ReturnsParsedConfiguration diff --git a/docs/verification/build-mark/configuration/report-config.md b/docs/verification/build-mark/configuration/report-config.md index 0f84b13f..b0e68e0d 100644 --- a/docs/verification/build-mark/configuration/report-config.md +++ b/docs/verification/build-mark/configuration/report-config.md @@ -1,20 +1,20 @@ -# ReportConfig +### ReportConfig -## Verification Approach +#### Verification Approach `ReportConfig` is verified through `ConfigurationTests.cs`. Tests write `.buildmark.yaml` files with a `report:` block and assert that `File`, `Depth`, and `IncludeKnownIssues` properties are correctly parsed or that invalid values produce error issues. No mocking is required. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | -------------------------------------------------------------------- | | File system | Tests create temporary `.buildmark.yaml` files in `Path.GetTempPath` | -## Test Scenarios +#### Test Scenarios -### BuildMarkConfigReader_ReadAsync_ValidReportSection_ReturnsParsedReportConfig +##### BuildMarkConfigReader_ReadAsync_ValidReportSection_ReturnsParsedReportConfig **Scenario**: A `.buildmark.yaml` with `report.file`, `report.depth: 2`, and `report.include-known-issues: true` is written; `BuildMarkConfigReader.ReadAsync` is called; @@ -25,7 +25,7 @@ correctly parsed or that invalid values produce error issues. No mocking is requ **Requirement coverage**: `BuildMark-ReportConfig-Properties`. -### BuildMarkConfigReader_ReadAsync_InvalidReportDepth_ReturnsErrorIssue +##### BuildMarkConfigReader_ReadAsync_InvalidReportDepth_ReturnsErrorIssue **Scenario**: A `.buildmark.yaml` with `report.depth: -1` is written; `BuildMarkConfigReader.ReadAsync` is called. @@ -35,7 +35,7 @@ correctly parsed or that invalid values produce error issues. No mocking is requ **Requirement coverage**: `BuildMark-ReportConfig-Properties`. -## Requirements Coverage +#### Requirements Coverage - **`BuildMark-ReportConfig-Properties`**: - BuildMarkConfigReader_ReadAsync_ValidReportSection_ReturnsParsedReportConfig diff --git a/docs/verification/build-mark/configuration/rule-config.md b/docs/verification/build-mark/configuration/rule-config.md index 89e97a1d..526498a3 100644 --- a/docs/verification/build-mark/configuration/rule-config.md +++ b/docs/verification/build-mark/configuration/rule-config.md @@ -1,21 +1,21 @@ -# RuleConfig +### RuleConfig -## Verification Approach +#### Verification Approach `RuleConfig` is verified through `ConfigurationTests.cs`. The test `BuildMarkConfig_CreateDefault_ContainsDependencyUpdatesSection` calls `BuildMarkConfig.CreateDefault()` and asserts on the `Route` and `Match` properties of the returned rules. No mocking is required. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | --------------- | | None | No mocks needed | -## Test Scenarios +#### Test Scenarios -### BuildMarkConfig_CreateDefault_ContainsDependencyUpdatesSection +##### BuildMarkConfig_CreateDefault_ContainsDependencyUpdatesSection **Scenario**: `BuildMarkConfig.CreateDefault()` is called; the returned `Rules` collection is inspected. @@ -27,7 +27,7 @@ route with a null match. **Requirement coverage**: `BuildMark-RuleConfig-Properties`. -## Requirements Coverage +#### Requirements Coverage - **`BuildMark-RuleConfig-Properties`**: - BuildMarkConfig_CreateDefault_ContainsDependencyUpdatesSection diff --git a/docs/verification/build-mark/configuration/rule-match-config.md b/docs/verification/build-mark/configuration/rule-match-config.md index 76f93074..b747ca34 100644 --- a/docs/verification/build-mark/configuration/rule-match-config.md +++ b/docs/verification/build-mark/configuration/rule-match-config.md @@ -1,21 +1,21 @@ -# RuleMatchConfig +### RuleMatchConfig -## Verification Approach +#### Verification Approach `RuleMatchConfig` is a data model class verified indirectly through `ItemRouterTests.cs`. Tests that exercise label-based and type-based matching use `RuleMatchConfig` instances within `RuleConfig` to control item routing. Case-insensitive matching tests confirm the match comparison behavior. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | ---------- | | None | Data class | -## Test Scenarios (Integration) +#### Test Scenarios (Integration) -### ItemRouter_Route_WithWorkItemTypeMatch_RoutesMatchingItem +##### ItemRouter_Route_WithWorkItemTypeMatch_RoutesMatchingItem **Scenario**: A `RuleMatchConfig` specifying a work item type is used; item with matching type is routed. @@ -24,7 +24,7 @@ matching type is routed. **Requirement coverage**: `BuildMark-Configuration-RuleMatchConfig` -### ItemRouter_Route_WithCaseInsensitiveLabelMatch_RoutesItem +##### ItemRouter_Route_WithCaseInsensitiveLabelMatch_RoutesItem **Scenario**: A `RuleMatchConfig` specifying a label is used; item with matching label (case-insensitive) is routed. @@ -33,7 +33,7 @@ label (case-insensitive) is routed. **Requirement coverage**: `BuildMark-Configuration-RuleMatchConfig` -### ItemRouter_Route_WithCaseInsensitiveSuppressedRoute_OmitsMatchingItem +##### ItemRouter_Route_WithCaseInsensitiveSuppressedRoute_OmitsMatchingItem **Scenario**: A `RuleMatchConfig` on a suppressed rule matches an item case-insensitively. @@ -41,7 +41,7 @@ label (case-insensitive) is routed. **Requirement coverage**: `BuildMark-Configuration-RuleMatchConfig` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-Configuration-RuleMatchConfig**: ItemRouter_Route_WithWorkItemTypeMatch_RoutesMatchingItem, diff --git a/docs/verification/build-mark/configuration/section-config.md b/docs/verification/build-mark/configuration/section-config.md index 36afae83..5a21cc66 100644 --- a/docs/verification/build-mark/configuration/section-config.md +++ b/docs/verification/build-mark/configuration/section-config.md @@ -1,21 +1,21 @@ -# SectionConfig +### SectionConfig -## Verification Approach +#### Verification Approach `SectionConfig` is verified through `ConfigurationTests.cs`. The test `BuildMarkConfig_CreateDefault_ContainsDependencyUpdatesSection` calls `BuildMarkConfig.CreateDefault()` and asserts on the `Id` and `Title` properties of the returned sections. No mocking is required. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | --------------- | | None | No mocks needed | -## Test Scenarios +#### Test Scenarios -### BuildMarkConfig_CreateDefault_ContainsDependencyUpdatesSection +##### BuildMarkConfig_CreateDefault_ContainsDependencyUpdatesSection **Scenario**: `BuildMarkConfig.CreateDefault()` is called; the returned `Sections` collection is inspected. @@ -26,7 +26,7 @@ inspected. **Requirement coverage**: `BuildMark-SectionConfig-Properties`. -## Requirements Coverage +#### Requirements Coverage - **`BuildMark-SectionConfig-Properties`**: - BuildMarkConfig_CreateDefault_ContainsDependencyUpdatesSection diff --git a/docs/verification/build-mark/program.md b/docs/verification/build-mark/program.md index c3d7f784..11ec4eaf 100644 --- a/docs/verification/build-mark/program.md +++ b/docs/verification/build-mark/program.md @@ -1,22 +1,22 @@ -# Program +## Program -## Verification Approach +### Verification Approach `Program` unit tests are in `ProgramTests.cs`. Each test constructs a `Context` object with controlled arguments and output capture, calls `Program.Run`, then asserts on the context output and exit code. The connector factory is injected via a context override to avoid live API calls where needed. -## Dependencies +### Dependencies | Mock / Stub | Reason | | ---------------------- | -------------------------------------------------------- | | `Context` | Constructed with controlled arguments and output capture | | Connector factory mock | Injected to avoid live API calls | -## Test Scenarios +### Test Scenarios -### Program_Version_ReturnsValidVersion +#### Program_Version_ReturnsValidVersion **Scenario**: `Program.Version` is accessed directly. @@ -24,7 +24,7 @@ to avoid live API calls where needed. **Requirement coverage**: `BuildMark-Program-Version` -### Program_Run_VersionFlag_OutputsVersionToConsole +#### Program_Run_VersionFlag_OutputsVersionToConsole **Scenario**: `Program.Run` is called with `Version = true` in context. @@ -32,7 +32,7 @@ to avoid live API calls where needed. **Requirement coverage**: `BuildMark-Program-Version` -### Program_Run_HelpFlag_OutputsHelpMessage +#### Program_Run_HelpFlag_OutputsHelpMessage **Scenario**: `Program.Run` is called with `Help = true` in context. @@ -40,7 +40,7 @@ to avoid live API calls where needed. **Requirement coverage**: `BuildMark-Program-Help` -### Program_Run_QuestionMarkFlag_OutputsHelpMessage +#### Program_Run_QuestionMarkFlag_OutputsHelpMessage **Scenario**: `Program.Run` is called with `?` argument. @@ -48,7 +48,7 @@ to avoid live API calls where needed. **Requirement coverage**: `BuildMark-Program-Help` -### Program_Run_LongHelpFlag_OutputsHelpMessage +#### Program_Run_LongHelpFlag_OutputsHelpMessage **Scenario**: `Program.Run` is called with `--help` argument. @@ -56,7 +56,7 @@ to avoid live API calls where needed. **Requirement coverage**: `BuildMark-Program-Help` -### Program_Run_ValidateFlag_OutputsValidationMessage +#### Program_Run_ValidateFlag_OutputsValidationMessage **Scenario**: `Program.Run` is called with `Validate = true`. @@ -64,7 +64,7 @@ to avoid live API calls where needed. **Requirement coverage**: `BuildMark-Program-Validate` -### Program_Run_ReportWithIncludeKnownIssuesFlag_GeneratesReportWithKnownIssues +#### Program_Run_ReportWithIncludeKnownIssuesFlag_GeneratesReportWithKnownIssues **Scenario**: `Program.Run` is called with report flags and `IncludeKnownIssues = true`. @@ -72,7 +72,7 @@ to avoid live API calls where needed. **Requirement coverage**: `BuildMark-Program-Report` -### Program_Run_LintFlagWithoutConfiguration_LeavesExitCodeAtZero +#### Program_Run_LintFlagWithoutConfiguration_LeavesExitCodeAtZero **Scenario**: `Program.Run` is called with `Lint = true` but no config present. @@ -80,7 +80,7 @@ to avoid live API calls where needed. **Requirement coverage**: `BuildMark-Program-Lint` -### Program_Run_InvalidBuildVersion_WritesErrorAndSetsExitCode +#### Program_Run_InvalidBuildVersion_WritesErrorAndSetsExitCode **Scenario**: `Program.Run` is called with an invalid build version. @@ -94,7 +94,7 @@ to avoid live API calls where needed. **Requirement coverage**: `BuildMark-Program-ErrorHandling-ConnectorFailure` -### Program_Run_WithSilentFlag_SuppressesOutput +#### Program_Run_WithSilentFlag_SuppressesOutput **Scenario**: `Program.Run` is called with `--silent` and `--help` flags in context. @@ -102,7 +102,7 @@ to avoid live API calls where needed. **Requirement coverage**: `BuildMark-Program-Silent` -### Program_Run_WithLogFlag_WritesToLogFile +#### Program_Run_WithLogFlag_WritesToLogFile **Scenario**: `Program.Run` is called with `--log ` flag pointing to a temporary file. @@ -110,7 +110,7 @@ to avoid live API calls where needed. **Requirement coverage**: `BuildMark-Program-Log` -### Program_Run_WithResultsFlag_WritesResultsFile +#### Program_Run_WithResultsFlag_WritesResultsFile **Scenario**: `Program.Run` is called with `--validate` and `--results ` flags. @@ -118,7 +118,7 @@ to avoid live API calls where needed. **Requirement coverage**: `BuildMark-Program-Results` -### Program_Run_WithBuildVersionFlag_AcceptsBuildVersion +#### Program_Run_WithBuildVersionFlag_AcceptsBuildVersion **Scenario**: `Program.Run` is called with `--build-version 3.2.1` and a mock connector. @@ -126,7 +126,7 @@ to avoid live API calls where needed. **Requirement coverage**: `BuildMark-Program-BuildVersion` -### Program_Run_WithDepthFlag_SetsHeadingDepth +#### Program_Run_WithDepthFlag_SetsHeadingDepth **Scenario**: `Program.Run` is called with `--depth 3` and a mock connector. @@ -134,7 +134,7 @@ to avoid live API calls where needed. **Requirement coverage**: `BuildMark-Program-Depth` -## Requirements Coverage +### Requirements Coverage - **BuildMark-Program-Version**: Program_Version_ReturnsValidVersion, Program_Run_VersionFlag_OutputsVersionToConsole diff --git a/docs/verification/build-mark/repo-connectors/repo-connectors.md b/docs/verification/build-mark/repo-connectors.md similarity index 77% rename from docs/verification/build-mark/repo-connectors/repo-connectors.md rename to docs/verification/build-mark/repo-connectors.md index 7716b028..ca6c16de 100644 --- a/docs/verification/build-mark/repo-connectors/repo-connectors.md +++ b/docs/verification/build-mark/repo-connectors.md @@ -1,6 +1,6 @@ -# RepoConnectors +## RepoConnectors -## Verification Approach +### Verification Approach The RepoConnectors subsystem is verified through `RepoConnectorsTests.cs`, which contains 33 subsystem-level integration tests. These tests exercise the connector @@ -8,7 +8,7 @@ factory, the GitHub connector, the Azure DevOps connector, and the Mock connecto through the full `GetBuildInformationAsync` pipeline using mock HTTP data. Individual unit tests for sub-components are described in the unit-level chapters. -## Dependencies +### Dependencies | Mock / Stub | Reason | | ------------------------ | ------------------------------------------------------------- | @@ -16,9 +16,9 @@ unit tests for sub-components are described in the unit-level chapters. | `MockRepoConnector` | Used directly for factory and base class tests | | `ProcessRunner` (real) | Used by ProcessRunner tests with actual OS commands | -## Test Scenarios +### Test Scenarios -### RepoConnectors_GitHubConnector_ImplementsInterface_ReturnsTrue +#### RepoConnectors_GitHubConnector_ImplementsInterface_ReturnsTrue **Scenario**: The GitHub connector instance is checked against `IRepoConnector`. @@ -26,7 +26,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-IRepoConnector` -### RepoConnectors_GitHubConnector_GetBuildInformation_WithMockedData_ReturnsValidBuildInformation +#### RepoConnectors_GitHubConnector_GetBuildInformation_WithMockedData_ReturnsValidBuildInformation **Scenario**: GitHub connector receives mocked GraphQL responses. @@ -34,7 +34,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### RepoConnectors_GitHubConnector_GetBuildInformation_WithMultipleVersions_SelectsCorrectBaseline +#### RepoConnectors_GitHubConnector_GetBuildInformation_WithMultipleVersions_SelectsCorrectBaseline **Scenario**: Multiple version tags exist; connector selects the correct baseline. @@ -42,7 +42,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### RepoConnectors_GitHubConnector_GetBuildInformation_WithPullRequests_GathersChanges +#### RepoConnectors_GitHubConnector_GetBuildInformation_WithPullRequests_GathersChanges **Scenario**: Mock data includes pull requests; connector gathers them as changes. @@ -50,7 +50,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### RepoConnectors_GitHubConnector_GetBuildInformation_WithOpenIssues_IdentifiesKnownIssues +#### RepoConnectors_GitHubConnector_GetBuildInformation_WithOpenIssues_IdentifiesKnownIssues **Scenario**: Mock data includes open issues; connector identifies them as known issues. @@ -58,7 +58,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### RepoConnectors_GitHubConnector_GetBuildInformation_ReleaseVersion_SkipsPreReleases +#### RepoConnectors_GitHubConnector_GetBuildInformation_ReleaseVersion_SkipsPreReleases **Scenario**: Build version is a release; pre-release tags in history are skipped. @@ -66,7 +66,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### RepoConnectors_ConnectorBase_MockConnector_ImplementsInterface +#### RepoConnectors_ConnectorBase_MockConnector_ImplementsInterface **Scenario**: Mock connector is checked against `IRepoConnector`. @@ -74,7 +74,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-IRepoConnector` -### RepoConnectors_ConnectorBase_GitHubConnector_ImplementsInterface +#### RepoConnectors_ConnectorBase_GitHubConnector_ImplementsInterface **Scenario**: GitHub connector class is checked for `RepoConnectorBase` inheritance. @@ -82,7 +82,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorBase` -### RepoConnectors_MockConnector_Constructor_CreatesInstance +#### RepoConnectors_MockConnector_Constructor_CreatesInstance **Scenario**: `MockRepoConnector` is constructed. @@ -90,7 +90,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-Mock` -### RepoConnectors_MockConnector_ImplementsInterface_ReturnsTrue +#### RepoConnectors_MockConnector_ImplementsInterface_ReturnsTrue **Scenario**: Mock connector is checked against `IRepoConnector`. @@ -98,7 +98,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-IRepoConnector` -### RepoConnectors_MockConnector_GetBuildInformation_ReturnsExpectedVersion +#### RepoConnectors_MockConnector_GetBuildInformation_ReturnsExpectedVersion **Scenario**: Mock connector's `GetBuildInformationAsync` is called. @@ -106,7 +106,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-Mock` -### RepoConnectors_MockConnector_GetBuildInformation_ReturnsCompleteInformation +#### RepoConnectors_MockConnector_GetBuildInformation_ReturnsCompleteInformation **Scenario**: Mock connector returns complete build information. @@ -114,7 +114,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-Mock` -### RepoConnectors_ProcessRunner_TryRunAsync_WithValidCommand_ReturnsOutput +#### RepoConnectors_ProcessRunner_TryRunAsync_WithValidCommand_ReturnsOutput **Scenario**: `ProcessRunner.TryRunAsync` with a valid OS command. @@ -122,7 +122,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-Utilities-ProcessRunner` -### RepoConnectors_ProcessRunner_TryRunAsync_WithInvalidCommand_ReturnsNull +#### RepoConnectors_ProcessRunner_TryRunAsync_WithInvalidCommand_ReturnsNull **Scenario**: `ProcessRunner.TryRunAsync` with an invalid command. @@ -130,7 +130,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-Utilities-ProcessRunner` -### RepoConnectors_ProcessRunner_TryRunAsync_WithNonZeroExitCode_ReturnsNull +#### RepoConnectors_ProcessRunner_TryRunAsync_WithNonZeroExitCode_ReturnsNull **Scenario**: `ProcessRunner.TryRunAsync` with a command that exits non-zero. @@ -138,7 +138,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-Utilities-ProcessRunner` -### RepoConnectors_ProcessRunner_RunAsync_WithValidCommand_ReturnsOutput +#### RepoConnectors_ProcessRunner_RunAsync_WithValidCommand_ReturnsOutput **Scenario**: `ProcessRunner.RunAsync` with a valid command. @@ -146,7 +146,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-Utilities-ProcessRunner` -### RepoConnectors_ProcessRunner_RunAsync_WithFailingCommand_ThrowsException +#### RepoConnectors_ProcessRunner_RunAsync_WithFailingCommand_ThrowsException **Scenario**: `ProcessRunner.RunAsync` with a failing command. @@ -154,7 +154,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-Utilities-ProcessRunner` -### RepoConnectors_Factory_Create_ReturnsConnector +#### RepoConnectors_Factory_Create_ReturnsConnector **Scenario**: `RepoConnectorFactory.Create` is called with no configuration. @@ -162,7 +162,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorFactory` -### RepoConnectors_Factory_Create_ReturnsGitHubConnectorForThisRepo +#### RepoConnectors_Factory_Create_ReturnsGitHubConnectorForThisRepo **Scenario**: Factory detects GitHub Actions environment or remote URL. @@ -170,7 +170,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorFactory` -### RepoConnectors_ItemControls_VisibilityPublic_ReturnsPublicVisibility +#### RepoConnectors_ItemControls_VisibilityPublic_ReturnsPublicVisibility **Scenario**: `ItemControlsParser.Parse` processes a block with `visibility: public`. @@ -178,7 +178,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### RepoConnectors_ItemControls_VisibilityInternal_ReturnsInternalVisibility +#### RepoConnectors_ItemControls_VisibilityInternal_ReturnsInternalVisibility **Scenario**: `ItemControlsParser.Parse` processes a block with `visibility: internal`. @@ -186,7 +186,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### RepoConnectors_ItemControls_TypeBug_ReturnsBugType +#### RepoConnectors_ItemControls_TypeBug_ReturnsBugType **Scenario**: `ItemControlsParser.Parse` processes a block with `type: bug`. @@ -194,7 +194,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### RepoConnectors_ItemControls_TypeFeature_ReturnsFeatureType +#### RepoConnectors_ItemControls_TypeFeature_ReturnsFeatureType **Scenario**: `ItemControlsParser.Parse` processes a block with `type: feature`. @@ -202,7 +202,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### RepoConnectors_ItemControls_AffectedVersions_ReturnsIntervalSet +#### RepoConnectors_ItemControls_AffectedVersions_ReturnsIntervalSet **Scenario**: `ItemControlsParser.Parse` processes a block with `affected-versions`. @@ -210,7 +210,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### RepoConnectors_ItemControls_HiddenBlock_ReturnsControls +#### RepoConnectors_ItemControls_HiddenBlock_ReturnsControls **Scenario**: `ItemControlsParser.Parse` processes a hidden buildmark block. @@ -218,7 +218,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### RepoConnectors_ItemControls_NoBlock_ReturnsNull +#### RepoConnectors_ItemControls_NoBlock_ReturnsNull **Scenario**: `ItemControlsParser.Parse` is called with text containing no buildmark block. @@ -226,7 +226,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### RepoConnectors_ItemRouter_MatchingRule_RoutesToSection +#### RepoConnectors_ItemRouter_MatchingRule_RoutesToSection **Scenario**: `ItemRouter.Route` routes an item matching a configured rule. @@ -234,7 +234,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-ItemRouter` -### RepoConnectors_ItemRouter_SuppressedRoute_OmitsItem +#### RepoConnectors_ItemRouter_SuppressedRoute_OmitsItem **Scenario**: `ItemRouter.Route` suppresses an item matching a suppressed rule. @@ -242,7 +242,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-ItemRouter` -### RepoConnectors_AzureDevOps_ImplementsInterface_ReturnsTrue +#### RepoConnectors_AzureDevOps_ImplementsInterface_ReturnsTrue **Scenario**: Azure DevOps connector is checked against `IRepoConnector`. @@ -250,7 +250,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-IRepoConnector` -### RepoConnectors_AzureDevOps_GetBuildInformation_WithMockedData_ReturnsValidBuildInformation +#### RepoConnectors_AzureDevOps_GetBuildInformation_WithMockedData_ReturnsValidBuildInformation **Scenario**: Azure DevOps connector receives mocked REST responses. @@ -258,7 +258,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### RepoConnectors_AzureDevOps_GetBuildInformation_WithPullRequests_GathersChanges +#### RepoConnectors_AzureDevOps_GetBuildInformation_WithPullRequests_GathersChanges **Scenario**: Mock data includes Azure DevOps pull requests. @@ -266,7 +266,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### RepoConnectors_AzureDevOps_GetBuildInformation_WithOpenWorkItems_IdentifiesKnownIssues +#### RepoConnectors_AzureDevOps_GetBuildInformation_WithOpenWorkItems_IdentifiesKnownIssues **Scenario**: Mock data includes open work items. @@ -274,7 +274,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### RepoConnectors_AzureDevOps_GetBuildInformation_ReleaseVersion_SkipsPreReleases +#### RepoConnectors_AzureDevOps_GetBuildInformation_ReleaseVersion_SkipsPreReleases **Scenario**: Release build; pre-release tags in history are skipped. @@ -282,7 +282,7 @@ unit tests for sub-components are described in the unit-level chapters. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -## Requirements Coverage +### Requirements Coverage - **BuildMark-RepoConnectors-IRepoConnector**: RepoConnectors_GitHubConnector_ImplementsInterface_ReturnsTrue, RepoConnectors_ConnectorBase_MockConnector_ImplementsInterface, diff --git a/docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops.md b/docs/verification/build-mark/repo-connectors/azure-devops.md similarity index 80% rename from docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops.md rename to docs/verification/build-mark/repo-connectors/azure-devops.md index ca3e2697..1602c2be 100644 --- a/docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops.md +++ b/docs/verification/build-mark/repo-connectors/azure-devops.md @@ -1,6 +1,6 @@ -# Azure DevOps +### Azure DevOps -## Verification Approach +#### Verification Approach The Azure DevOps sub-subsystem is verified through `AzureDevOpsTests.cs` (5 subsystem- level tests), `AzureDevOpsRepoConnectorTests.cs` (25 unit tests), @@ -8,15 +8,15 @@ level tests), `AzureDevOpsRepoConnectorTests.cs` (25 unit tests), tests). The subsystem tests exercise the full Azure DevOps data pipeline through mock HTTP responses. The unit tests are described in the individual unit chapters. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ------------------------ | -------------------------------------------------- | | `MockHttpMessageHandler` | Intercepts HTTP calls to the Azure DevOps REST API | -## Test Scenarios (Subsystem-Level, AzureDevOpsTests.cs) +#### Test Scenarios (Subsystem-Level, AzureDevOpsTests.cs) -### AzureDevOps_ImplementsInterface_ReturnsTrue +##### AzureDevOps_ImplementsInterface_ReturnsTrue **Scenario**: `AzureDevOpsRepoConnector` is checked against `IRepoConnector`. @@ -24,7 +24,7 @@ HTTP responses. The unit tests are described in the individual unit chapters. **Requirement coverage**: `BuildMark-RepoConnectors-IRepoConnector` -### AzureDevOps_GetBuildInformation_WithMockedData_ReturnsValidBuildInformation +##### AzureDevOps_GetBuildInformation_WithMockedData_ReturnsValidBuildInformation **Scenario**: Azure DevOps connector receives mocked REST API data. @@ -32,7 +32,7 @@ HTTP responses. The unit tests are described in the individual unit chapters. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOps_GetBuildInformation_WithWorkItems_GathersChanges +##### AzureDevOps_GetBuildInformation_WithWorkItems_GathersChanges **Scenario**: Mock data includes work items linked to commits. @@ -40,7 +40,7 @@ HTTP responses. The unit tests are described in the individual unit chapters. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOps_GetBuildInformation_WithOpenBugs_IdentifiesKnownIssues +##### AzureDevOps_GetBuildInformation_WithOpenBugs_IdentifiesKnownIssues **Scenario**: Mock data includes open bug work items. @@ -48,7 +48,7 @@ HTTP responses. The unit tests are described in the individual unit chapters. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOps_GetBuildInformation_ReleaseVersion_SkipsPreReleases +##### AzureDevOps_GetBuildInformation_ReleaseVersion_SkipsPreReleases **Scenario**: Build version is a release; pre-release tags in history are skipped. @@ -56,7 +56,7 @@ HTTP responses. The unit tests are described in the individual unit chapters. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-RepoConnectors-IRepoConnector**: AzureDevOps_ImplementsInterface_ReturnsTrue - **BuildMark-RepoConnectors-AzureDevOps**: AzureDevOps_GetBuildInformation_WithMockedData_ReturnsValidBuildInformation, diff --git a/docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops-api-types.md b/docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md similarity index 78% rename from docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops-api-types.md rename to docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md index 5cd39a2b..ea3fa3dd 100644 --- a/docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops-api-types.md +++ b/docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md @@ -1,6 +1,6 @@ -# AzureDevOpsApiTypes +#### AzureDevOpsApiTypes -## Verification Approach +##### Verification Approach `AzureDevOpsApiTypes` contains the DTO types used to deserialize Azure DevOps REST API responses. These types have no dedicated test class; they are verified indirectly @@ -8,15 +8,15 @@ through `AzureDevOpsRestClientTests.cs` tests that exercise JSON deserialization mocked API responses and through `WorkItemMapperTests.cs` tests that consume the deserialized data. -## Dependencies +##### Dependencies | Mock / Stub | Reason | | ------------------------ | ------------------------------------------------------------ | | `MockHttpMessageHandler` | Provides JSON payloads whose structure matches the DTO types | -## Test Scenarios (via AzureDevOpsRestClientTests.cs) +##### Test Scenarios (via AzureDevOpsRestClientTests.cs) -### AzureDevOpsRestClient_GetTagsAsync_ValidResponse_ReturnsTags +###### AzureDevOpsRestClient_GetTagsAsync_ValidResponse_ReturnsTags **Scenario**: Tag REST response is deserialized into tag DTOs. @@ -24,7 +24,7 @@ deserialized data. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOpsApiTypes` -### AzureDevOpsRestClient_GetCommitsAsync_ValidResponse_ReturnsCommits +###### AzureDevOpsRestClient_GetCommitsAsync_ValidResponse_ReturnsCommits **Scenario**: Commits REST response is deserialized into commit DTOs. @@ -32,7 +32,7 @@ deserialized data. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOpsApiTypes` -### AzureDevOpsRestClient_GetWorkItemsAsync_ValidResponse_ReturnsWorkItems +###### AzureDevOpsRestClient_GetWorkItemsAsync_ValidResponse_ReturnsWorkItems **Scenario**: Work items REST response is deserialized into work item DTOs. @@ -40,7 +40,7 @@ deserialized data. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOpsApiTypes` -### AzureDevOpsRestClient_GetWorkItemLinksAsync_ValidResponse_ReturnsWorkItemLinks +###### AzureDevOpsRestClient_GetWorkItemLinksAsync_ValidResponse_ReturnsWorkItemLinks **Scenario**: Work item links REST response is deserialized into work item link DTOs. @@ -48,7 +48,7 @@ deserialized data. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOpsApiTypes` -## Requirements Coverage +##### Requirements Coverage - **BuildMark-RepoConnectors-AzureDevOpsApiTypes**: Verified indirectly through all 8 tests in `AzureDevOpsRestClientTests.cs` and all 10 tests in diff --git a/docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops-repo-connector.md b/docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md similarity index 70% rename from docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops-repo-connector.md rename to docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md index 0a471bec..3f9c3bd1 100644 --- a/docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops-repo-connector.md +++ b/docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md @@ -1,6 +1,6 @@ -# AzureDevOpsRepoConnector +#### AzureDevOpsRepoConnector -## Verification Approach +##### Verification Approach `AzureDevOpsRepoConnector` is tested through `AzureDevOpsRepoConnectorTests.cs`, which contains 25 unit tests. The tests exercise constructor behavior, the full @@ -8,15 +8,15 @@ which contains 25 unit tests. The tests exercise constructor behavior, the full configuration, known issues filtering by affected versions, and edge cases including work item deduplication and version tag handling. -## Dependencies +##### Dependencies | Mock / Stub | Reason | | ------------------------ | ----------------------------------------------------------- | | `MockHttpMessageHandler` | Intercepts all HTTP calls to the Azure DevOps REST endpoint | -## Test Scenarios +##### Test Scenarios -### AzureDevOpsRepoConnector_Constructor_CreatesInstance +###### AzureDevOpsRepoConnector_Constructor_CreatesInstance **Scenario**: Connector is constructed with no configuration. @@ -24,7 +24,7 @@ work item deduplication and version tag handling. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_Constructor_WithConfig_StoresConfigurationOverrides +###### AzureDevOpsRepoConnector_Constructor_WithConfig_StoresConfigurationOverrides **Scenario**: Connector is constructed with an `AzureDevOpsConnectorConfig`. @@ -32,7 +32,7 @@ work item deduplication and version tag handling. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_ImplementsInterface_ReturnsTrue +###### AzureDevOpsRepoConnector_ImplementsInterface_ReturnsTrue **Scenario**: Connector is checked against `IRepoConnector`. @@ -40,7 +40,7 @@ work item deduplication and version tag handling. **Requirement coverage**: `BuildMark-RepoConnectors-IRepoConnector` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithMockedData_ReturnsValidBuildInformation +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithMockedData_ReturnsValidBuildInformation **Scenario**: `GetBuildInformationAsync` processes mocked REST API responses. @@ -49,7 +49,7 @@ changes, and known issues. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithMultipleVersions_SelectsCorrectBaseline +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithMultipleVersions_SelectsCorrectBaseline **Scenario**: Multiple version tags exist in the mocked response. @@ -57,7 +57,7 @@ changes, and known issues. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithWorkItems_GathersChangesCorrectly +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithWorkItems_GathersChangesCorrectly **Scenario**: Mocked data includes work items linked to commits. @@ -65,7 +65,7 @@ changes, and known issues. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithOpenBugs_IdentifiesKnownIssues +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithOpenBugs_IdentifiesKnownIssues **Scenario**: Mocked data includes open bug work items. @@ -73,7 +73,7 @@ changes, and known issues. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_PreReleaseWithSameCommitHash_SkipsToNextDifferentHash +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_PreReleaseWithSameCommitHash_SkipsToNextDifferentHash **Scenario**: A pre-release tag shares the same commit hash as the build version. @@ -81,7 +81,7 @@ changes, and known issues. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_ReleaseVersion_SkipsAllPreReleases +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_ReleaseVersion_SkipsAllPreReleases **Scenario**: Build version is a release; prior history contains pre-release tags. @@ -89,7 +89,7 @@ changes, and known issues. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_PreReleaseNotInHistory_UsesLatestDifferentHash +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_PreReleaseNotInHistory_UsesLatestDifferentHash **Scenario**: Pre-release tag is not found in commit history; connector falls back. @@ -97,7 +97,7 @@ changes, and known issues. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_PreReleaseAllPreviousSameHash_ReturnsNullBaseline +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_PreReleaseAllPreviousSameHash_ReturnsNullBaseline **Scenario**: All previous tags share the same commit hash. @@ -105,7 +105,7 @@ changes, and known issues. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithDuplicateWorkItem_DeduplicatesChanges +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithDuplicateWorkItem_DeduplicatesChanges **Scenario**: Mocked data contains the same work item linked to multiple commits. @@ -113,7 +113,7 @@ changes, and known issues. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_VisibilityInternal_ExcludesItem +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_VisibilityInternal_ExcludesItem **Scenario**: A work item has `visibility: internal` in its buildmark block. @@ -121,7 +121,7 @@ changes, and known issues. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_VisibilityPublic_IncludesItem +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_VisibilityPublic_IncludesItem **Scenario**: A work item has `visibility: public` in its buildmark block. @@ -129,7 +129,7 @@ changes, and known issues. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_TypeBugOverride_ClassifiesAsBug +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_TypeBugOverride_ClassifiesAsBug **Scenario**: A work item has `type: bug` in its buildmark block. @@ -137,7 +137,7 @@ changes, and known issues. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_TypeFeatureOverride_ClassifiesAsFeature +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_TypeFeatureOverride_ClassifiesAsFeature **Scenario**: A work item has `type: feature` in its buildmark block. @@ -145,7 +145,7 @@ changes, and known issues. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_Configure_WithRules_HasRulesReturnsTrue +###### AzureDevOpsRepoConnector_Configure_WithRules_HasRulesReturnsTrue **Scenario**: `Configure` is called with routing rules. @@ -153,7 +153,7 @@ changes, and known issues. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithConfiguredRules_PopulatesRoutedSections +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithConfiguredRules_PopulatesRoutedSections **Scenario**: Connector is configured with routing rules and run with mock data. @@ -161,7 +161,7 @@ changes, and known issues. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_KnownIssues_FilteredByAffectedVersions +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_KnownIssues_FilteredByAffectedVersions **Scenario**: Known issues have `affected-versions` set; build version is outside the range. @@ -170,7 +170,7 @@ range. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_ClosedBugWithMatchingAffectedVersions_IsKnownIssue +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_ClosedBugWithMatchingAffectedVersions_IsKnownIssue **Scenario**: A closed bug has `affected-versions` that includes the build version. @@ -178,7 +178,7 @@ range. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithNoTags_ReturnsEmptyBuildInformation +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithNoTags_ReturnsEmptyBuildInformation **Scenario**: Repository has no version tags. @@ -186,7 +186,7 @@ range. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithNoCommitsBetweenVersions_ReturnsEmptyChanges +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithNoCommitsBetweenVersions_ReturnsEmptyChanges **Scenario**: No commits exist between the build version and the baseline. @@ -194,7 +194,7 @@ range. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_WorkItemWithNoBugType_NotKnownIssue +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_WorkItemWithNoBugType_NotKnownIssue **Scenario**: Open work item is not of type bug. @@ -202,7 +202,7 @@ range. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_WorkItemWithCompletedState_NotKnownIssue +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_WorkItemWithCompletedState_NotKnownIssue **Scenario**: Bug work item is in a completed state. @@ -210,7 +210,7 @@ range. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithAzureDevOpsUrl_GeneratesChangelogLink +###### AzureDevOpsRepoConnector_GetBuildInformationAsync_WithAzureDevOpsUrl_GeneratesChangelogLink **Scenario**: Repository URL is an Azure DevOps URL. @@ -218,7 +218,7 @@ range. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOps` -## Requirements Coverage +##### Requirements Coverage - **BuildMark-RepoConnectors-IRepoConnector**: AzureDevOpsRepoConnector_ImplementsInterface_ReturnsTrue diff --git a/docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops-rest-client.md b/docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md similarity index 76% rename from docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops-rest-client.md rename to docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md index a3f37335..d58e7287 100644 --- a/docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops-rest-client.md +++ b/docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md @@ -1,21 +1,21 @@ -# AzureDevOpsRestClient +#### AzureDevOpsRestClient -## Verification Approach +##### Verification Approach `AzureDevOpsRestClient` is tested through `AzureDevOpsRestClientTests.cs`, which contains 8 unit tests. The tests cover successful data retrieval for tags, commits, work items, and work item links, as well as HTTP error handling and invalid JSON handling. -## Dependencies +##### Dependencies | Mock / Stub | Reason | | ------------------------ | ------------------------------------------------------------ | | `MockHttpMessageHandler` | Intercepts all HTTP calls to the Azure DevOps REST endpoints | -## Test Scenarios +##### Test Scenarios -### AzureDevOpsRestClient_GetTagsAsync_ValidResponse_ReturnsTags +###### AzureDevOpsRestClient_GetTagsAsync_ValidResponse_ReturnsTags **Scenario**: Valid REST API response for the tags endpoint. @@ -23,7 +23,7 @@ handling. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOpsRestClient` -### AzureDevOpsRestClient_GetTagsAsync_HttpError_ReturnsEmptyList +###### AzureDevOpsRestClient_GetTagsAsync_HttpError_ReturnsEmptyList **Scenario**: Tags endpoint returns a non-success status code. @@ -31,7 +31,7 @@ handling. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOpsRestClient` -### AzureDevOpsRestClient_GetCommitsAsync_ValidResponse_ReturnsCommits +###### AzureDevOpsRestClient_GetCommitsAsync_ValidResponse_ReturnsCommits **Scenario**: Valid REST API response for the commits endpoint. @@ -39,7 +39,7 @@ handling. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOpsRestClient` -### AzureDevOpsRestClient_GetCommitsAsync_HttpError_ReturnsEmptyList +###### AzureDevOpsRestClient_GetCommitsAsync_HttpError_ReturnsEmptyList **Scenario**: Commits endpoint returns a non-success status code. @@ -47,7 +47,7 @@ handling. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOpsRestClient` -### AzureDevOpsRestClient_GetWorkItemsAsync_ValidResponse_ReturnsWorkItems +###### AzureDevOpsRestClient_GetWorkItemsAsync_ValidResponse_ReturnsWorkItems **Scenario**: Valid REST API response for the work items endpoint. @@ -55,7 +55,7 @@ handling. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOpsRestClient` -### AzureDevOpsRestClient_GetWorkItemsAsync_HttpError_ReturnsEmptyList +###### AzureDevOpsRestClient_GetWorkItemsAsync_HttpError_ReturnsEmptyList **Scenario**: Work items endpoint returns a non-success status code. @@ -63,7 +63,7 @@ handling. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOpsRestClient` -### AzureDevOpsRestClient_GetWorkItemLinksAsync_ValidResponse_ReturnsWorkItemLinks +###### AzureDevOpsRestClient_GetWorkItemLinksAsync_ValidResponse_ReturnsWorkItemLinks **Scenario**: Valid REST API response for the work item links endpoint. @@ -71,7 +71,7 @@ handling. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOpsRestClient` -### AzureDevOpsRestClient_GetWorkItemLinksAsync_HttpError_ReturnsEmptyList +###### AzureDevOpsRestClient_GetWorkItemLinksAsync_HttpError_ReturnsEmptyList **Scenario**: Work item links endpoint returns a non-success status code. @@ -79,7 +79,7 @@ handling. **Requirement coverage**: `BuildMark-RepoConnectors-AzureDevOpsRestClient` -## Requirements Coverage +##### Requirements Coverage - **BuildMark-RepoConnectors-AzureDevOpsRestClient**: All 8 tests in `AzureDevOpsRestClientTests.cs` diff --git a/docs/verification/build-mark/repo-connectors/azure-dev-ops/work-item-mapper.md b/docs/verification/build-mark/repo-connectors/azure-devops/work-item-mapper.md similarity index 78% rename from docs/verification/build-mark/repo-connectors/azure-dev-ops/work-item-mapper.md rename to docs/verification/build-mark/repo-connectors/azure-devops/work-item-mapper.md index 357b701f..a9dfc0c3 100644 --- a/docs/verification/build-mark/repo-connectors/azure-dev-ops/work-item-mapper.md +++ b/docs/verification/build-mark/repo-connectors/azure-devops/work-item-mapper.md @@ -1,6 +1,6 @@ -# WorkItemMapper +#### WorkItemMapper -## Verification Approach +##### Verification Approach `WorkItemMapper` is tested through `WorkItemMapperTests.cs`, which contains 10 unit tests. The tests verify mapping of Azure DevOps work items to the BuildMark model - @@ -8,15 +8,15 @@ classification of features and bugs, title and description extraction, change li generation, and handling of known issue identification based on work item type and state. -## Dependencies +##### Dependencies | Mock / Stub | Reason | | -------------------- | ----------------------------------------------------------- | | `WorkItem` test data | Constructed in-line with specific types, states, and fields | -## Test Scenarios +##### Test Scenarios -### WorkItemMapper_MapToItemInfo_Bug_ReturnsBugType +###### WorkItemMapper_MapToItemInfo_Bug_ReturnsBugType **Scenario**: A work item with type `"Bug"` is mapped. @@ -24,7 +24,7 @@ state. **Requirement coverage**: `BuildMark-RepoConnectors-WorkItemMapper` -### WorkItemMapper_MapToItemInfo_Feature_ReturnsFeatureType +###### WorkItemMapper_MapToItemInfo_Feature_ReturnsFeatureType **Scenario**: A work item with type `"Feature"` is mapped. @@ -32,7 +32,7 @@ state. **Requirement coverage**: `BuildMark-RepoConnectors-WorkItemMapper` -### WorkItemMapper_MapToItemInfo_UserStory_ReturnsFeatureType +###### WorkItemMapper_MapToItemInfo_UserStory_ReturnsFeatureType **Scenario**: A work item with type `"User Story"` is mapped. @@ -40,7 +40,7 @@ state. **Requirement coverage**: `BuildMark-RepoConnectors-WorkItemMapper` -### WorkItemMapper_MapToItemInfo_Task_ReturnsOtherType +###### WorkItemMapper_MapToItemInfo_Task_ReturnsOtherType **Scenario**: A work item with type `"Task"` is mapped. @@ -48,7 +48,7 @@ state. **Requirement coverage**: `BuildMark-RepoConnectors-WorkItemMapper` -### WorkItemMapper_MapToItemInfo_ExtractsTitle +###### WorkItemMapper_MapToItemInfo_ExtractsTitle **Scenario**: A work item has a title. @@ -56,7 +56,7 @@ state. **Requirement coverage**: `BuildMark-RepoConnectors-WorkItemMapper` -### WorkItemMapper_MapToItemInfo_ExtractsDescription +###### WorkItemMapper_MapToItemInfo_ExtractsDescription **Scenario**: A work item has a description. @@ -64,7 +64,7 @@ state. **Requirement coverage**: `BuildMark-RepoConnectors-WorkItemMapper` -### WorkItemMapper_MapToItemInfo_GeneratesWebLink +###### WorkItemMapper_MapToItemInfo_GeneratesWebLink **Scenario**: A work item has an ID and a valid organization URL. @@ -72,7 +72,7 @@ state. **Requirement coverage**: `BuildMark-RepoConnectors-WorkItemMapper` -### WorkItemMapper_IsKnownIssue_OpenBug_ReturnsTrue +###### WorkItemMapper_IsKnownIssue_OpenBug_ReturnsTrue **Scenario**: Work item is an open bug. @@ -80,7 +80,7 @@ state. **Requirement coverage**: `BuildMark-RepoConnectors-WorkItemMapper` -### WorkItemMapper_IsKnownIssue_ClosedBug_ReturnsFalse +###### WorkItemMapper_IsKnownIssue_ClosedBug_ReturnsFalse **Scenario**: Work item is a closed bug. @@ -88,7 +88,7 @@ state. **Requirement coverage**: `BuildMark-RepoConnectors-WorkItemMapper` -### WorkItemMapper_IsKnownIssue_OpenFeature_ReturnsFalse +###### WorkItemMapper_IsKnownIssue_OpenFeature_ReturnsFalse **Scenario**: Work item is an open feature (not a bug). @@ -96,6 +96,6 @@ state. **Requirement coverage**: `BuildMark-RepoConnectors-WorkItemMapper` -## Requirements Coverage +##### Requirements Coverage - **BuildMark-RepoConnectors-WorkItemMapper**: All 10 tests in `WorkItemMapperTests.cs` diff --git a/docs/verification/build-mark/repo-connectors/github/github.md b/docs/verification/build-mark/repo-connectors/github.md similarity index 80% rename from docs/verification/build-mark/repo-connectors/github/github.md rename to docs/verification/build-mark/repo-connectors/github.md index 0111f8d1..3be43356 100644 --- a/docs/verification/build-mark/repo-connectors/github/github.md +++ b/docs/verification/build-mark/repo-connectors/github.md @@ -1,21 +1,21 @@ -# GitHub +### GitHub -## Verification Approach +#### Verification Approach The GitHub sub-subsystem is verified through `GitHubTests.cs` (6 subsystem-level tests), `GitHubRepoConnectorTests.cs` (22 unit tests), and 5 `GitHubGraphQLClient*Tests.cs` files (41 tests). The subsystem tests exercise the full GitHub data pipeline through mock HTTP responses. The unit tests are described in the individual unit chapters. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ------------------------ | ----------------------------------------------- | | `MockHttpMessageHandler` | Intercepts HTTP calls to the GitHub GraphQL API | -## Test Scenarios (Subsystem-Level, GitHubTests.cs) +#### Test Scenarios (Subsystem-Level, GitHubTests.cs) -### GitHub_ImplementsInterface_ReturnsTrue +##### GitHub_ImplementsInterface_ReturnsTrue **Scenario**: `GitHubRepoConnector` is checked against `IRepoConnector`. @@ -23,7 +23,7 @@ mock HTTP responses. The unit tests are described in the individual unit chapter **Requirement coverage**: `BuildMark-RepoConnectors-IRepoConnector` -### GitHub_GetBuildInformation_WithMockedData_ReturnsValidBuildInformation +##### GitHub_GetBuildInformation_WithMockedData_ReturnsValidBuildInformation **Scenario**: GitHub connector receives mocked GraphQL data. @@ -31,7 +31,7 @@ mock HTTP responses. The unit tests are described in the individual unit chapter **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHub_GetBuildInformation_WithMultipleVersions_SelectsCorrectBaseline +##### GitHub_GetBuildInformation_WithMultipleVersions_SelectsCorrectBaseline **Scenario**: Multiple tags exist; connector selects the correct prior release. @@ -39,7 +39,7 @@ mock HTTP responses. The unit tests are described in the individual unit chapter **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHub_GetBuildInformation_WithPullRequests_GathersChanges +##### GitHub_GetBuildInformation_WithPullRequests_GathersChanges **Scenario**: Mock data contains pull requests merged since the baseline. @@ -47,7 +47,7 @@ mock HTTP responses. The unit tests are described in the individual unit chapter **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHub_GetBuildInformation_WithOpenIssues_IdentifiesKnownIssues +##### GitHub_GetBuildInformation_WithOpenIssues_IdentifiesKnownIssues **Scenario**: Mock data contains open issues. @@ -55,7 +55,7 @@ mock HTTP responses. The unit tests are described in the individual unit chapter **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHub_GetBuildInformation_ReleaseVersion_SkipsPreReleases +##### GitHub_GetBuildInformation_ReleaseVersion_SkipsPreReleases **Scenario**: Build version is a release; pre-release tags in the history are skipped. @@ -63,7 +63,7 @@ mock HTTP responses. The unit tests are described in the individual unit chapter **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-RepoConnectors-IRepoConnector**: GitHub_ImplementsInterface_ReturnsTrue - **BuildMark-RepoConnectors-GitHub**: GitHub_GetBuildInformation_WithMockedData_ReturnsValidBuildInformation, diff --git a/docs/verification/build-mark/repo-connectors/github/git-hub-graph-ql-client.md b/docs/verification/build-mark/repo-connectors/github/git-hub-graph-ql-client.md index bf45b53b..24333d31 100644 --- a/docs/verification/build-mark/repo-connectors/github/git-hub-graph-ql-client.md +++ b/docs/verification/build-mark/repo-connectors/github/git-hub-graph-ql-client.md @@ -1,6 +1,6 @@ -# GitHubGraphQLClient +#### GitHubGraphQLClient -## Verification Approach +##### Verification Approach `GitHubGraphQLClient` is tested through five dedicated test files, each covering one query method. All tests use `MockHttpMessageHandler` to intercept HTTP requests and @@ -17,15 +17,15 @@ pagination. | `GitHubGraphQLClientGetPullRequestsTests.cs` | `GetPullRequestsAsync` | 9 | | `GitHubGraphQLClientGetReleasesTests.cs` | `GetReleasesAsync` | 8 | -## Dependencies +##### Dependencies | Mock / Stub | Reason | | ------------------------ | ------------------------------------------------------- | | `MockHttpMessageHandler` | Intercepts HTTP calls; returns controlled JSON payloads | -## Test Scenarios +##### Test Scenarios -### GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_ValidResponse_ReturnsIssueIds +###### GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_ValidResponse_ReturnsIssueIds **Scenario**: Valid GraphQL response is returned for a linked-issues query. @@ -33,7 +33,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_NoIssues_ReturnsEmptyList +###### GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_NoIssues_ReturnsEmptyList **Scenario**: Response contains no linked issues. @@ -41,7 +41,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_MissingData_ReturnsEmptyList +###### GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_MissingData_ReturnsEmptyList **Scenario**: Response JSON is missing the data structure. @@ -49,7 +49,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_HttpError_ReturnsEmptyList +###### GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_HttpError_ReturnsEmptyList **Scenario**: HTTP request returns a non-success status code. @@ -57,7 +57,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_InvalidJson_ReturnsEmptyList +###### GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_InvalidJson_ReturnsEmptyList **Scenario**: Response body is not valid JSON. @@ -65,7 +65,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_SingleIssue_ReturnsOneIssueId +###### GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_SingleIssue_ReturnsOneIssueId **Scenario**: Response contains exactly one linked issue. @@ -73,7 +73,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_MissingNumberProperty_SkipsInvalidNodes +###### GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_MissingNumberProperty_SkipsInvalidNodes **Scenario**: One node in the response is missing the `number` property. @@ -81,7 +81,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_WithPagination_ReturnsAllIssues +###### GitHubGraphQLClient_FindIssueIdsLinkedToPullRequestAsync_WithPagination_ReturnsAllIssues **Scenario**: Response uses pagination (multiple pages of linked issues). @@ -89,7 +89,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetAllIssuesAsync_ValidResponse_ReturnsIssues +###### GitHubGraphQLClient_GetAllIssuesAsync_ValidResponse_ReturnsIssues **Scenario**: Valid response for GetAllIssues query. @@ -97,7 +97,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetAllIssuesAsync_NoIssues_ReturnsEmptyList +###### GitHubGraphQLClient_GetAllIssuesAsync_NoIssues_ReturnsEmptyList **Scenario**: Response contains no issues. @@ -105,7 +105,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetAllIssuesAsync_MissingData_ReturnsEmptyList +###### GitHubGraphQLClient_GetAllIssuesAsync_MissingData_ReturnsEmptyList **Scenario**: Response is missing the data structure. @@ -113,7 +113,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetAllIssuesAsync_NullNodes_ReturnsEmptyList +###### GitHubGraphQLClient_GetAllIssuesAsync_NullNodes_ReturnsEmptyList **Scenario**: Response has null nodes array. @@ -121,7 +121,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetAllIssuesAsync_InvalidIssues_FiltersThemOut +###### GitHubGraphQLClient_GetAllIssuesAsync_InvalidIssues_FiltersThemOut **Scenario**: Response contains some invalid issue objects. @@ -129,7 +129,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetAllIssuesAsync_WithPagination_ReturnsAllIssues +###### GitHubGraphQLClient_GetAllIssuesAsync_WithPagination_ReturnsAllIssues **Scenario**: Issues span multiple pages. @@ -137,7 +137,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetAllIssuesAsync_Exception_ReturnsEmptyList +###### GitHubGraphQLClient_GetAllIssuesAsync_Exception_ReturnsEmptyList **Scenario**: An exception is thrown during the HTTP request. @@ -145,7 +145,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetAllIssuesAsync_ValidResponse_ReturnsIssuesWithBody +###### GitHubGraphQLClient_GetAllIssuesAsync_ValidResponse_ReturnsIssuesWithBody **Scenario**: Valid response includes issues with a body field. @@ -153,7 +153,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetAllTagsAsync_ValidResponse_ReturnsTagNodes +###### GitHubGraphQLClient_GetAllTagsAsync_ValidResponse_ReturnsTagNodes **Scenario**: Valid response for GetAllTags query. @@ -161,7 +161,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetAllTagsAsync_NoTags_ReturnsEmptyList +###### GitHubGraphQLClient_GetAllTagsAsync_NoTags_ReturnsEmptyList **Scenario**: Response contains no tags. @@ -169,7 +169,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetAllTagsAsync_MissingData_ReturnsEmptyList +###### GitHubGraphQLClient_GetAllTagsAsync_MissingData_ReturnsEmptyList **Scenario**: Response is missing the data structure. @@ -177,7 +177,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetAllTagsAsync_HttpError_ReturnsEmptyList +###### GitHubGraphQLClient_GetAllTagsAsync_HttpError_ReturnsEmptyList **Scenario**: HTTP request returns a non-success status code. @@ -185,7 +185,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetAllTagsAsync_InvalidJson_ReturnsEmptyList +###### GitHubGraphQLClient_GetAllTagsAsync_InvalidJson_ReturnsEmptyList **Scenario**: Response body is not valid JSON. @@ -193,7 +193,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetAllTagsAsync_SingleTag_ReturnsOneTagNode +###### GitHubGraphQLClient_GetAllTagsAsync_SingleTag_ReturnsOneTagNode **Scenario**: Response contains exactly one tag. @@ -201,7 +201,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetAllTagsAsync_MissingNameProperty_SkipsInvalidNodes +###### GitHubGraphQLClient_GetAllTagsAsync_MissingNameProperty_SkipsInvalidNodes **Scenario**: One tag node is missing the `name` property. @@ -209,7 +209,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetAllTagsAsync_WithPagination_ReturnsAllTags +###### GitHubGraphQLClient_GetAllTagsAsync_WithPagination_ReturnsAllTags **Scenario**: Tags span multiple pages. @@ -217,7 +217,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetCommitsAsync_ValidResponse_ReturnsCommitShas +###### GitHubGraphQLClient_GetCommitsAsync_ValidResponse_ReturnsCommitShas **Scenario**: Valid response for GetCommits query. @@ -225,7 +225,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetCommitsAsync_NoCommits_ReturnsEmptyList +###### GitHubGraphQLClient_GetCommitsAsync_NoCommits_ReturnsEmptyList **Scenario**: Response contains no commits. @@ -233,7 +233,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetCommitsAsync_MissingData_ReturnsEmptyList +###### GitHubGraphQLClient_GetCommitsAsync_MissingData_ReturnsEmptyList **Scenario**: Response is missing the data structure. @@ -241,7 +241,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetCommitsAsync_HttpError_ReturnsEmptyList +###### GitHubGraphQLClient_GetCommitsAsync_HttpError_ReturnsEmptyList **Scenario**: HTTP error response received. @@ -249,7 +249,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetCommitsAsync_InvalidJson_ReturnsEmptyList +###### GitHubGraphQLClient_GetCommitsAsync_InvalidJson_ReturnsEmptyList **Scenario**: Invalid JSON in response body. @@ -257,7 +257,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetCommitsAsync_SingleCommit_ReturnsOneCommitSha +###### GitHubGraphQLClient_GetCommitsAsync_SingleCommit_ReturnsOneCommitSha **Scenario**: Response contains exactly one commit. @@ -265,7 +265,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetCommitsAsync_MissingOidProperty_SkipsInvalidNodes +###### GitHubGraphQLClient_GetCommitsAsync_MissingOidProperty_SkipsInvalidNodes **Scenario**: One commit node is missing the `oid` property. @@ -273,7 +273,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetCommitsAsync_WithPagination_ReturnsAllCommits +###### GitHubGraphQLClient_GetCommitsAsync_WithPagination_ReturnsAllCommits **Scenario**: Commits span multiple pages. @@ -281,7 +281,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetPullRequestsAsync_ValidResponse_ReturnsPullRequests +###### GitHubGraphQLClient_GetPullRequestsAsync_ValidResponse_ReturnsPullRequests **Scenario**: Valid response for GetPullRequests query. @@ -289,7 +289,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetPullRequestsAsync_NoPullRequests_ReturnsEmptyList +###### GitHubGraphQLClient_GetPullRequestsAsync_NoPullRequests_ReturnsEmptyList **Scenario**: Response contains no pull requests. @@ -297,7 +297,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetPullRequestsAsync_MissingData_ReturnsEmptyList +###### GitHubGraphQLClient_GetPullRequestsAsync_MissingData_ReturnsEmptyList **Scenario**: Response is missing the data structure. @@ -305,7 +305,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetPullRequestsAsync_HttpError_ReturnsEmptyList +###### GitHubGraphQLClient_GetPullRequestsAsync_HttpError_ReturnsEmptyList **Scenario**: HTTP error response received. @@ -313,7 +313,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetPullRequestsAsync_InvalidJson_ReturnsEmptyList +###### GitHubGraphQLClient_GetPullRequestsAsync_InvalidJson_ReturnsEmptyList **Scenario**: Invalid JSON in response body. @@ -321,7 +321,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetPullRequestsAsync_SinglePullRequest_ReturnsOnePullRequest +###### GitHubGraphQLClient_GetPullRequestsAsync_SinglePullRequest_ReturnsOnePullRequest **Scenario**: Response contains exactly one pull request. @@ -329,7 +329,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetPullRequestsAsync_MissingNumberOrTitle_SkipsInvalidNodes +###### GitHubGraphQLClient_GetPullRequestsAsync_MissingNumberOrTitle_SkipsInvalidNodes **Scenario**: One pull request node is missing `number` or `title`. @@ -337,7 +337,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetPullRequestsAsync_WithPagination_ReturnsAllPullRequests +###### GitHubGraphQLClient_GetPullRequestsAsync_WithPagination_ReturnsAllPullRequests **Scenario**: Pull requests span multiple pages. @@ -345,7 +345,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetPullRequestsAsync_ValidResponse_ReturnsPullRequestsWithBody +###### GitHubGraphQLClient_GetPullRequestsAsync_ValidResponse_ReturnsPullRequestsWithBody **Scenario**: Valid response includes pull requests with a body field. @@ -353,7 +353,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetReleasesAsync_ValidResponse_ReturnsReleaseTagNames +###### GitHubGraphQLClient_GetReleasesAsync_ValidResponse_ReturnsReleaseTagNames **Scenario**: Valid response for GetReleases query. @@ -361,7 +361,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetReleasesAsync_NoReleases_ReturnsEmptyList +###### GitHubGraphQLClient_GetReleasesAsync_NoReleases_ReturnsEmptyList **Scenario**: Response contains no releases. @@ -369,7 +369,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetReleasesAsync_MissingData_ReturnsEmptyList +###### GitHubGraphQLClient_GetReleasesAsync_MissingData_ReturnsEmptyList **Scenario**: Response is missing the data structure. @@ -377,7 +377,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetReleasesAsync_HttpError_ReturnsEmptyList +###### GitHubGraphQLClient_GetReleasesAsync_HttpError_ReturnsEmptyList **Scenario**: HTTP error response received. @@ -385,7 +385,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetReleasesAsync_InvalidJson_ReturnsEmptyList +###### GitHubGraphQLClient_GetReleasesAsync_InvalidJson_ReturnsEmptyList **Scenario**: Invalid JSON in response body. @@ -393,7 +393,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetReleasesAsync_SingleRelease_ReturnsOneTagName +###### GitHubGraphQLClient_GetReleasesAsync_SingleRelease_ReturnsOneTagName **Scenario**: Response contains exactly one release. @@ -401,7 +401,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetReleasesAsync_MissingTagNameProperty_SkipsInvalidNodes +###### GitHubGraphQLClient_GetReleasesAsync_MissingTagNameProperty_SkipsInvalidNodes **Scenario**: One release node is missing the `tagName` property. @@ -409,7 +409,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -### GitHubGraphQLClient_GetReleasesAsync_WithPagination_ReturnsAllReleases +###### GitHubGraphQLClient_GetReleasesAsync_WithPagination_ReturnsAllReleases **Scenario**: Releases span multiple pages. @@ -417,7 +417,7 @@ pagination. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLClient` -## Requirements Coverage +##### Requirements Coverage - **BuildMark-RepoConnectors-GitHubGraphQLClient**: All 41 tests across the five `GitHubGraphQLClient*Tests.cs` files diff --git a/docs/verification/build-mark/repo-connectors/github/git-hub-graph-ql-types.md b/docs/verification/build-mark/repo-connectors/github/git-hub-graph-ql-types.md index e8a03f85..c225c1d8 100644 --- a/docs/verification/build-mark/repo-connectors/github/git-hub-graph-ql-types.md +++ b/docs/verification/build-mark/repo-connectors/github/git-hub-graph-ql-types.md @@ -1,21 +1,21 @@ -# GitHubGraphQLTypes +#### GitHubGraphQLTypes -## Verification Approach +##### Verification Approach `GitHubGraphQLTypes` contains the data transfer object (DTO) types used to deserialize GitHub GraphQL API responses. These types have no dedicated test class; they are verified indirectly through all `GitHubGraphQLClient*Tests.cs` tests that exercise JSON deserialization of mocked API responses. -## Dependencies +##### Dependencies | Mock / Stub | Reason | | ------------------------ | ------------------------------------------------------------ | | `MockHttpMessageHandler` | Provides JSON payloads whose structure matches the DTO types | -## Test Scenarios (via GitHubGraphQLClient*Tests.cs) +##### Test Scenarios (via GitHubGraphQLClient*Tests.cs) -### GitHubGraphQLClient_GetAllIssuesAsync_ValidResponse_ReturnsIssuesWithBody +###### GitHubGraphQLClient_GetAllIssuesAsync_ValidResponse_ReturnsIssuesWithBody **Scenario**: GraphQL response for issues is deserialized into issue DTOs. @@ -23,7 +23,7 @@ JSON deserialization of mocked API responses. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLTypes` -### GitHubGraphQLClient_GetPullRequestsAsync_ValidResponse_ReturnsPullRequestsWithBody +###### GitHubGraphQLClient_GetPullRequestsAsync_ValidResponse_ReturnsPullRequestsWithBody **Scenario**: GraphQL response for pull requests is deserialized into pull request DTOs. @@ -31,7 +31,7 @@ JSON deserialization of mocked API responses. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLTypes` -### GitHubGraphQLClient_GetAllTagsAsync_ValidResponse_ReturnsTagNodes +###### GitHubGraphQLClient_GetAllTagsAsync_ValidResponse_ReturnsTagNodes **Scenario**: GraphQL response for tags is deserialized into tag node DTOs. @@ -39,7 +39,7 @@ JSON deserialization of mocked API responses. **Requirement coverage**: `BuildMark-RepoConnectors-GitHubGraphQLTypes` -## Requirements Coverage +##### Requirements Coverage - **BuildMark-RepoConnectors-GitHubGraphQLTypes**: Verified indirectly through all 41 tests in the `GitHubGraphQLClient*Tests.cs` files diff --git a/docs/verification/build-mark/repo-connectors/github/git-hub-repo-connector.md b/docs/verification/build-mark/repo-connectors/github/git-hub-repo-connector.md index 71e819e3..dde24997 100644 --- a/docs/verification/build-mark/repo-connectors/github/git-hub-repo-connector.md +++ b/docs/verification/build-mark/repo-connectors/github/git-hub-repo-connector.md @@ -1,6 +1,6 @@ -# GitHubRepoConnector +#### GitHubRepoConnector -## Verification Approach +##### Verification Approach `GitHubRepoConnector` is tested through `GitHubRepoConnectorTests.cs`, which contains 22 unit tests. The tests exercise constructor behavior (with and without config), @@ -8,15 +8,15 @@ the full `GetBuildInformationAsync` pipeline with various scenarios, visibility type overrides, routing configuration, known issues filtering by affected versions, and edge cases such as duplicate commit SHAs and substring label matching. -## Dependencies +##### Dependencies | Mock / Stub | Reason | | ------------------------ | -------------------------------------------------------- | | `MockHttpMessageHandler` | Intercepts all HTTP calls to the GitHub GraphQL endpoint | -## Test Scenarios +##### Test Scenarios -### GitHubRepoConnector_Constructor_CreatesInstance +###### GitHubRepoConnector_Constructor_CreatesInstance **Scenario**: `GitHubRepoConnector` is constructed with no configuration. @@ -24,7 +24,7 @@ and edge cases such as duplicate commit SHAs and substring label matching. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_Constructor_WithConfig_StoresConfigurationOverrides +###### GitHubRepoConnector_Constructor_WithConfig_StoresConfigurationOverrides **Scenario**: `GitHubRepoConnector` is constructed with a `GitHubConnectorConfig`. @@ -34,7 +34,7 @@ equals `"https://api.github.com"`. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_ImplementsInterface_ReturnsTrue +###### GitHubRepoConnector_ImplementsInterface_ReturnsTrue **Scenario**: Connector is checked against `IRepoConnector`. @@ -42,7 +42,7 @@ equals `"https://api.github.com"`. **Requirement coverage**: `BuildMark-RepoConnectors-IRepoConnector` -### GitHubRepoConnector_GetBuildInformationAsync_WithMockedData_ReturnsValidBuildInformation +###### GitHubRepoConnector_GetBuildInformationAsync_WithMockedData_ReturnsValidBuildInformation **Scenario**: `GetBuildInformationAsync` processes mocked GraphQL responses. @@ -51,7 +51,7 @@ changes, and known issues. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_GetBuildInformationAsync_WithMultipleVersions_SelectsCorrectPreviousVersionAndGeneratesChangelogLink +###### GitHubRepoConnector_GetBuildInformationAsync_WithMultipleVersions_SelectsCorrectPreviousVersionAndGeneratesChangelogLink **Scenario**: Multiple version tags exist in the mocked response. @@ -59,7 +59,7 @@ changes, and known issues. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_GetBuildInformationAsync_WithPullRequests_GathersChangesCorrectly +###### GitHubRepoConnector_GetBuildInformationAsync_WithPullRequests_GathersChangesCorrectly **Scenario**: Mocked data includes pull requests with labels. @@ -68,7 +68,7 @@ classification. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_GetBuildInformationAsync_WithOpenIssues_IdentifiesKnownIssues +###### GitHubRepoConnector_GetBuildInformationAsync_WithOpenIssues_IdentifiesKnownIssues **Scenario**: Mocked data includes open issues. @@ -76,7 +76,7 @@ classification. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_GetBuildInformationAsync_PreReleaseWithSameCommitHash_SkipsToNextDifferentHash +###### GitHubRepoConnector_GetBuildInformationAsync_PreReleaseWithSameCommitHash_SkipsToNextDifferentHash **Scenario**: A pre-release tag shares the same commit hash as the build version. @@ -84,7 +84,7 @@ classification. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_GetBuildInformationAsync_ReleaseVersion_SkipsAllPreReleases +###### GitHubRepoConnector_GetBuildInformationAsync_ReleaseVersion_SkipsAllPreReleases **Scenario**: Build version is a release; prior history contains pre-release tags. @@ -92,7 +92,7 @@ classification. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_GetBuildInformationAsync_PreReleaseNotInHistory_UsesLatestDifferentHash +###### GitHubRepoConnector_GetBuildInformationAsync_PreReleaseNotInHistory_UsesLatestDifferentHash **Scenario**: Pre-release tag is not found in commit history; connector falls back. @@ -100,7 +100,7 @@ classification. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_GetBuildInformationAsync_PreReleaseAllPreviousSameHash_ReturnsNullBaseline +###### GitHubRepoConnector_GetBuildInformationAsync_PreReleaseAllPreviousSameHash_ReturnsNullBaseline **Scenario**: All previous tags share the same commit hash as the build version. @@ -108,7 +108,7 @@ classification. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_GetBuildInformationAsync_WithDuplicateMergeCommitSha_DoesNotThrow +###### GitHubRepoConnector_GetBuildInformationAsync_WithDuplicateMergeCommitSha_DoesNotThrow **Scenario**: Mocked data contains pull requests with duplicate merge commit SHAs. @@ -116,7 +116,7 @@ classification. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_GetBuildInformationAsync_PrWithSubstringMatchLabel_NotClassifiedAsBug +###### GitHubRepoConnector_GetBuildInformationAsync_PrWithSubstringMatchLabel_NotClassifiedAsBug **Scenario**: A pull request has a label that is a substring of `"bug"` (e.g., `"b"`). @@ -124,7 +124,7 @@ classification. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_GetBuildInformationAsync_IssueWithSubstringMatchLabel_NotClassifiedAsKnownIssue +###### GitHubRepoConnector_GetBuildInformationAsync_IssueWithSubstringMatchLabel_NotClassifiedAsKnownIssue **Scenario**: An issue has a label that is a substring of a known issue label. @@ -132,7 +132,7 @@ classification. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_GetBuildInformationAsync_VisibilityInternal_ExcludesItem +###### GitHubRepoConnector_GetBuildInformationAsync_VisibilityInternal_ExcludesItem **Scenario**: An item has `visibility: internal` in its buildmark block. @@ -140,7 +140,7 @@ classification. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_GetBuildInformationAsync_VisibilityPublic_IncludesItem +###### GitHubRepoConnector_GetBuildInformationAsync_VisibilityPublic_IncludesItem **Scenario**: An item has `visibility: public` in its buildmark block. @@ -148,7 +148,7 @@ classification. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_GetBuildInformationAsync_TypeBugOverride_ClassifiesAsBug +###### GitHubRepoConnector_GetBuildInformationAsync_TypeBugOverride_ClassifiesAsBug **Scenario**: An item has `type: bug` in its buildmark block. @@ -156,7 +156,7 @@ classification. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_GetBuildInformationAsync_TypeFeatureOverride_ClassifiesAsFeature +###### GitHubRepoConnector_GetBuildInformationAsync_TypeFeatureOverride_ClassifiesAsFeature **Scenario**: An item has `type: feature` in its buildmark block. @@ -164,7 +164,7 @@ classification. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_Configure_WithRules_HasRulesReturnsTrue +###### GitHubRepoConnector_Configure_WithRules_HasRulesReturnsTrue **Scenario**: `Configure` is called with routing rules. @@ -172,7 +172,7 @@ classification. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_GetBuildInformationAsync_WithConfiguredRules_PopulatesRoutedSections +###### GitHubRepoConnector_GetBuildInformationAsync_WithConfiguredRules_PopulatesRoutedSections **Scenario**: Connector is configured with routing rules and run with mock data. @@ -180,7 +180,7 @@ classification. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_GetBuildInformationAsync_KnownIssues_FilteredByAffectedVersions +###### GitHubRepoConnector_GetBuildInformationAsync_KnownIssues_FilteredByAffectedVersions **Scenario**: Known issues have `affected-versions` set; build version is outside the range. @@ -188,7 +188,7 @@ classification. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -### GitHubRepoConnector_GetBuildInformationAsync_ClosedBugWithMatchingAffectedVersions_IsKnownIssue +###### GitHubRepoConnector_GetBuildInformationAsync_ClosedBugWithMatchingAffectedVersions_IsKnownIssue **Scenario**: A closed bug has `affected-versions` that includes the build version. @@ -196,7 +196,7 @@ classification. **Requirement coverage**: `BuildMark-RepoConnectors-GitHub` -## Requirements Coverage +##### Requirements Coverage - **BuildMark-RepoConnectors-IRepoConnector**: GitHubRepoConnector_ImplementsInterface_ReturnsTrue - **BuildMark-RepoConnectors-GitHub**: All remaining 21 tests in `GitHubRepoConnectorTests.cs` diff --git a/docs/verification/build-mark/repo-connectors/i-repo-connector.md b/docs/verification/build-mark/repo-connectors/i-repo-connector.md index 778db671..36b3be7d 100644 --- a/docs/verification/build-mark/repo-connectors/i-repo-connector.md +++ b/docs/verification/build-mark/repo-connectors/i-repo-connector.md @@ -1,6 +1,6 @@ -# IRepoConnector +### IRepoConnector -## Verification Approach +#### Verification Approach `IRepoConnector` is an interface with no dedicated test class. Its contract is verified through all tests that exercise concrete implementations: `GitHubRepoConnector`, @@ -8,15 +8,15 @@ verified through all tests that exercise concrete implementations: `GitHubRepoCo against the interface via cast or type-assertion tests that confirm the concrete class implements `IRepoConnector`. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | --------- | | None | Interface | -## Test Scenarios (Integration via Implementations) +#### Test Scenarios (Integration via Implementations) -### RepoConnectors_GitHubConnector_ImplementsInterface_ReturnsTrue +##### RepoConnectors_GitHubConnector_ImplementsInterface_ReturnsTrue **Scenario**: `GitHubRepoConnector` instance is checked for `IRepoConnector` implementation. @@ -24,7 +24,7 @@ implements `IRepoConnector`. **Requirement coverage**: `BuildMark-RepoConnectors-IRepoConnector` -### RepoConnectors_MockConnector_ImplementsInterface_ReturnsTrue +##### RepoConnectors_MockConnector_ImplementsInterface_ReturnsTrue **Scenario**: `MockRepoConnector` instance is checked for `IRepoConnector` implementation. @@ -32,7 +32,7 @@ implements `IRepoConnector`. **Requirement coverage**: `BuildMark-RepoConnectors-IRepoConnector` -### RepoConnectors_AzureDevOps_ImplementsInterface_ReturnsTrue +##### RepoConnectors_AzureDevOps_ImplementsInterface_ReturnsTrue **Scenario**: `AzureDevOpsRepoConnector` instance is checked for `IRepoConnector` implementation. @@ -41,7 +41,7 @@ implementation. **Requirement coverage**: `BuildMark-RepoConnectors-IRepoConnector` -### GitHubRepoConnector_ImplementsInterface_ReturnsTrue +##### GitHubRepoConnector_ImplementsInterface_ReturnsTrue **Scenario**: `GitHubRepoConnector` type check against `IRepoConnector`. @@ -49,7 +49,7 @@ implementation. **Requirement coverage**: `BuildMark-RepoConnectors-IRepoConnector` -### MockRepoConnector_ImplementsInterface +##### MockRepoConnector_ImplementsInterface **Scenario**: `MockRepoConnector` type check against `IRepoConnector`. @@ -57,7 +57,7 @@ implementation. **Requirement coverage**: `BuildMark-RepoConnectors-IRepoConnector` -### AzureDevOpsRepoConnector_ImplementsInterface_ReturnsTrue +##### AzureDevOpsRepoConnector_ImplementsInterface_ReturnsTrue **Scenario**: `AzureDevOpsRepoConnector` type check against `IRepoConnector`. @@ -65,7 +65,7 @@ implementation. **Requirement coverage**: `BuildMark-RepoConnectors-IRepoConnector` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-RepoConnectors-IRepoConnector**: RepoConnectors_GitHubConnector_ImplementsInterface_ReturnsTrue, diff --git a/docs/verification/build-mark/repo-connectors/item-controls-info.md b/docs/verification/build-mark/repo-connectors/item-controls-info.md index 70644b75..9d30184c 100644 --- a/docs/verification/build-mark/repo-connectors/item-controls-info.md +++ b/docs/verification/build-mark/repo-connectors/item-controls-info.md @@ -1,21 +1,21 @@ -# ItemControlsInfo +### ItemControlsInfo -## Verification Approach +#### Verification Approach `ItemControlsInfo` is a data model class with no dedicated test class. It is verified indirectly through `ItemControlsTests.cs` and `ItemControlsParserTests.cs`. The parser tests assert on the resulting `ItemControlsInfo` instances, confirming that visibility, type, and affected versions fields are populated correctly. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | ---------- | | None | Data class | -## Test Scenarios (via ItemControlsTests.cs - 13 tests) +#### Test Scenarios (via ItemControlsTests.cs - 13 tests) -### ItemControls_Parse_WithVisibilityPublic_ReturnsPublicVisibility +##### ItemControls_Parse_WithVisibilityPublic_ReturnsPublicVisibility **Scenario**: A buildmark block with `visibility: public` is parsed. @@ -23,7 +23,7 @@ type, and affected versions fields are populated correctly. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsInfo` -### ItemControls_Parse_WithVisibilityInternal_ReturnsInternalVisibility +##### ItemControls_Parse_WithVisibilityInternal_ReturnsInternalVisibility **Scenario**: A buildmark block with `visibility: internal` is parsed. @@ -31,7 +31,7 @@ type, and affected versions fields are populated correctly. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsInfo` -### ItemControls_Parse_WithTypeBug_ReturnsBugType +##### ItemControls_Parse_WithTypeBug_ReturnsBugType **Scenario**: A buildmark block with `type: bug` is parsed. @@ -39,7 +39,7 @@ type, and affected versions fields are populated correctly. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsInfo` -### ItemControls_Parse_WithTypeFeature_ReturnsFeatureType +##### ItemControls_Parse_WithTypeFeature_ReturnsFeatureType **Scenario**: A buildmark block with `type: feature` is parsed. @@ -47,7 +47,7 @@ type, and affected versions fields are populated correctly. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsInfo` -### ItemControls_Parse_WithAffectedVersions_ReturnsIntervalSet +##### ItemControls_Parse_WithAffectedVersions_ReturnsIntervalSet **Scenario**: A buildmark block with `affected-versions` is parsed. @@ -55,7 +55,7 @@ type, and affected versions fields are populated correctly. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsInfo` -### ItemControls_Parse_WithHiddenBlock_ReturnsControls +##### ItemControls_Parse_WithHiddenBlock_ReturnsControls **Scenario**: A hidden buildmark block is parsed. @@ -63,7 +63,7 @@ type, and affected versions fields are populated correctly. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsInfo` -### ItemControls_Parse_WithNoBlock_ReturnsNull +##### ItemControls_Parse_WithNoBlock_ReturnsNull **Scenario**: Text with no buildmark block is parsed. @@ -71,6 +71,6 @@ type, and affected versions fields are populated correctly. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsInfo` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-RepoConnectors-ItemControlsInfo**: All 13 tests in `ItemControlsTests.cs` diff --git a/docs/verification/build-mark/repo-connectors/item-controls-parser.md b/docs/verification/build-mark/repo-connectors/item-controls-parser.md index 6e331bbe..bd357090 100644 --- a/docs/verification/build-mark/repo-connectors/item-controls-parser.md +++ b/docs/verification/build-mark/repo-connectors/item-controls-parser.md @@ -1,6 +1,6 @@ -# ItemControlsParser +### ItemControlsParser -## Verification Approach +#### Verification Approach `ItemControlsParser` is tested through `ItemControlsParserTests.cs`, which contains 15 unit tests. The tests cover parsing `null` and empty descriptions, descriptions @@ -8,15 +8,15 @@ with no block, and descriptions containing a buildmark block with various field combinations (visibility, type, affected-versions, hidden). Unknown keys and unrecognized values are tested for graceful ignorance. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | ---------- | | None | Pure logic | -## Test Scenarios +#### Test Scenarios -### ItemControlsParser_Parse_WithNullDescription_ReturnsNull +##### ItemControlsParser_Parse_WithNullDescription_ReturnsNull **Scenario**: `ItemControlsParser.Parse` is called with `null`. @@ -24,7 +24,7 @@ unrecognized values are tested for graceful ignorance. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### ItemControlsParser_Parse_WithEmptyDescription_ReturnsNull +##### ItemControlsParser_Parse_WithEmptyDescription_ReturnsNull **Scenario**: `ItemControlsParser.Parse` is called with an empty string. @@ -32,7 +32,7 @@ unrecognized values are tested for graceful ignorance. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### ItemControlsParser_Parse_WithNoBlock_ReturnsNull +##### ItemControlsParser_Parse_WithNoBlock_ReturnsNull **Scenario**: `ItemControlsParser.Parse` is called with text that contains no buildmark block. @@ -41,7 +41,7 @@ buildmark block. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### ItemControlsParser_Parse_WithVisibilityPublic_ReturnsPublicVisibility +##### ItemControlsParser_Parse_WithVisibilityPublic_ReturnsPublicVisibility **Scenario**: Description contains a buildmark block with `visibility: public`. @@ -49,7 +49,7 @@ buildmark block. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### ItemControlsParser_Parse_WithVisibilityInternal_ReturnsInternalVisibility +##### ItemControlsParser_Parse_WithVisibilityInternal_ReturnsInternalVisibility **Scenario**: Description contains a buildmark block with `visibility: internal`. @@ -57,7 +57,7 @@ buildmark block. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### ItemControlsParser_Parse_WithTypeBug_ReturnsBugType +##### ItemControlsParser_Parse_WithTypeBug_ReturnsBugType **Scenario**: Description contains a buildmark block with `type: bug`. @@ -65,7 +65,7 @@ buildmark block. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### ItemControlsParser_Parse_WithTypeFeature_ReturnsFeatureType +##### ItemControlsParser_Parse_WithTypeFeature_ReturnsFeatureType **Scenario**: Description contains a buildmark block with `type: feature`. @@ -73,7 +73,7 @@ buildmark block. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### ItemControlsParser_Parse_WithAffectedVersions_ReturnsIntervalSet +##### ItemControlsParser_Parse_WithAffectedVersions_ReturnsIntervalSet **Scenario**: Description contains a buildmark block with `affected-versions`. @@ -81,7 +81,7 @@ buildmark block. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### ItemControlsParser_Parse_WithHiddenBlock_ReturnsControls +##### ItemControlsParser_Parse_WithHiddenBlock_ReturnsControls **Scenario**: Description contains a hidden (but valid) buildmark block. @@ -89,7 +89,7 @@ buildmark block. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### ItemControlsParser_Parse_WithHiddenBlockVisibilityInternal_ReturnsInternalVisibility +##### ItemControlsParser_Parse_WithHiddenBlockVisibilityInternal_ReturnsInternalVisibility **Scenario**: Hidden block contains `visibility: internal`. @@ -97,7 +97,7 @@ buildmark block. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### ItemControlsParser_Parse_WithUnknownKey_IgnoresKey +##### ItemControlsParser_Parse_WithUnknownKey_IgnoresKey **Scenario**: Buildmark block contains an unrecognized key. @@ -105,7 +105,7 @@ buildmark block. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### ItemControlsParser_Parse_WithUnrecognizedVisibilityValue_IgnoresValue +##### ItemControlsParser_Parse_WithUnrecognizedVisibilityValue_IgnoresValue **Scenario**: Buildmark block contains `visibility: unknown-value`. @@ -113,7 +113,7 @@ buildmark block. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### ItemControlsParser_Parse_WithUnrecognizedTypeValue_IgnoresValue +##### ItemControlsParser_Parse_WithUnrecognizedTypeValue_IgnoresValue **Scenario**: Buildmark block contains `type: unknown-value`. @@ -121,7 +121,7 @@ buildmark block. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### ItemControlsParser_Parse_AllFields_ReturnsCompleteInfo +##### ItemControlsParser_Parse_AllFields_ReturnsCompleteInfo **Scenario**: Buildmark block contains visibility, type, and affected-versions. @@ -129,7 +129,7 @@ buildmark block. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -### ItemControlsParser_Parse_WithUnrecognizedAffectedVersionsValue_IgnoresValue +##### ItemControlsParser_Parse_WithUnrecognizedAffectedVersionsValue_IgnoresValue **Scenario**: Buildmark block contains an invalid `affected-versions` value. @@ -137,7 +137,7 @@ buildmark block. **Requirement coverage**: `BuildMark-RepoConnectors-ItemControlsParser` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-RepoConnectors-ItemControlsParser**: All 15 tests in `ItemControlsParserTests.cs` diff --git a/docs/verification/build-mark/repo-connectors/item-router.md b/docs/verification/build-mark/repo-connectors/item-router.md index ac44f419..bab1d9e2 100644 --- a/docs/verification/build-mark/repo-connectors/item-router.md +++ b/docs/verification/build-mark/repo-connectors/item-router.md @@ -1,13 +1,13 @@ -# ItemRouter +### ItemRouter -## Verification Approach +#### Verification Approach `ItemRouter` is tested through `ItemRouterTests.cs`, which contains 8 unit tests. The tests cover matching rules (with and without a match block), suppression rules, type-based matching, label-based matching (case-insensitive), routing to new sections, and default section fallback. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ---------------- | ------------------------------------------------------------ | @@ -15,9 +15,9 @@ and default section fallback. | `SectionConfig` | Provided as test input to define available sections | | `RuleConfig` | Provided as test input to define routing rules | -## Test Scenarios +#### Test Scenarios -### ItemRouter_Route_MatchingRuleRoutesItemToConfiguredSection +##### ItemRouter_Route_MatchingRuleRoutesItemToConfiguredSection **Scenario**: An item matching a configured rule's label is routed. @@ -25,7 +25,7 @@ and default section fallback. **Requirement coverage**: `BuildMark-RepoConnectors-ItemRouter` -### ItemRouter_Route_SuppressedRouteOmitsMatchingItem +##### ItemRouter_Route_SuppressedRouteOmitsMatchingItem **Scenario**: An item matching a suppressed rule is processed. @@ -33,7 +33,7 @@ and default section fallback. **Requirement coverage**: `BuildMark-RepoConnectors-ItemRouter` -### ItemRouter_Route_WithNullMatchBlock_MatchesAllItems +##### ItemRouter_Route_WithNullMatchBlock_MatchesAllItems **Scenario**: A rule with a `null` match block is configured; all items are tested. @@ -41,7 +41,7 @@ and default section fallback. **Requirement coverage**: `BuildMark-RepoConnectors-ItemRouter` -### ItemRouter_Route_WithWorkItemTypeMatch_RoutesMatchingItem +##### ItemRouter_Route_WithWorkItemTypeMatch_RoutesMatchingItem **Scenario**: A rule matching a specific work item type is applied. @@ -49,7 +49,7 @@ and default section fallback. **Requirement coverage**: `BuildMark-RepoConnectors-ItemRouter` -### ItemRouter_Route_WithNoMatchingRule_RoutesToDefaultSection +##### ItemRouter_Route_WithNoMatchingRule_RoutesToDefaultSection **Scenario**: An item that does not match any rule is processed. @@ -57,7 +57,7 @@ and default section fallback. **Requirement coverage**: `BuildMark-RepoConnectors-ItemRouter` -### ItemRouter_Route_ItemNotInConfiguredSections_CreatesNewSection +##### ItemRouter_Route_ItemNotInConfiguredSections_CreatesNewSection **Scenario**: A rule routes an item to a section name not in `SectionConfig`. @@ -65,7 +65,7 @@ and default section fallback. **Requirement coverage**: `BuildMark-RepoConnectors-ItemRouter` -### ItemRouter_Route_WithCaseInsensitiveLabelMatch_RoutesItem +##### ItemRouter_Route_WithCaseInsensitiveLabelMatch_RoutesItem **Scenario**: Rule matches a label `"bug"` and item has label `"Bug"`. @@ -73,7 +73,7 @@ and default section fallback. **Requirement coverage**: `BuildMark-RepoConnectors-ItemRouter` -### ItemRouter_Route_WithCaseInsensitiveSuppressedRoute_OmitsMatchingItem +##### ItemRouter_Route_WithCaseInsensitiveSuppressedRoute_OmitsMatchingItem **Scenario**: Suppressed rule matches a label case-insensitively. @@ -81,6 +81,6 @@ and default section fallback. **Requirement coverage**: `BuildMark-RepoConnectors-ItemRouter` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-RepoConnectors-ItemRouter**: All 8 tests in `ItemRouterTests.cs` diff --git a/docs/verification/build-mark/repo-connectors/mock/mock.md b/docs/verification/build-mark/repo-connectors/mock.md similarity index 79% rename from docs/verification/build-mark/repo-connectors/mock/mock.md rename to docs/verification/build-mark/repo-connectors/mock.md index a73d033f..f4edccd6 100644 --- a/docs/verification/build-mark/repo-connectors/mock/mock.md +++ b/docs/verification/build-mark/repo-connectors/mock.md @@ -1,21 +1,21 @@ -# Mock +### Mock -## Verification Approach +#### Verification Approach The Mock sub-subsystem is verified through `MockTests.cs` (3 subsystem-level tests) and `MockRepoConnectorTests.cs` (11 unit tests). The subsystem tests confirm integration of the mock connector within the broader pipeline. The unit tests are described in the individual unit chapter. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | --------- | | None | Pure mock | -## Test Scenarios (Subsystem-Level, MockTests.cs) +#### Test Scenarios (Subsystem-Level, MockTests.cs) -### Mock_ImplementsInterface_ReturnsTrue +##### Mock_ImplementsInterface_ReturnsTrue **Scenario**: `MockRepoConnector` is checked against `IRepoConnector`. @@ -23,7 +23,7 @@ described in the individual unit chapter. **Requirement coverage**: `BuildMark-RepoConnectors-IRepoConnector` -### Mock_GetBuildInformation_WithMockedData_ReturnsValidBuildInformation +##### Mock_GetBuildInformation_WithMockedData_ReturnsValidBuildInformation **Scenario**: Mock connector is configured with direct data and `GetBuildInformationAsync` is called. @@ -32,7 +32,7 @@ is called. **Requirement coverage**: `BuildMark-RepoConnectors-Mock` -### Mock_GetBuildInformation_WithNoData_ReturnsEmptyBuildInformation +##### Mock_GetBuildInformation_WithNoData_ReturnsEmptyBuildInformation **Scenario**: Mock connector is not configured; `GetBuildInformationAsync` is called. @@ -40,7 +40,7 @@ is called. **Requirement coverage**: `BuildMark-RepoConnectors-Mock` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-RepoConnectors-IRepoConnector**: Mock_ImplementsInterface_ReturnsTrue - **BuildMark-RepoConnectors-Mock**: Mock_GetBuildInformation_WithMockedData_ReturnsValidBuildInformation, diff --git a/docs/verification/build-mark/repo-connectors/mock/mock-repo-connector.md b/docs/verification/build-mark/repo-connectors/mock/mock-repo-connector.md index 14680475..8fc94547 100644 --- a/docs/verification/build-mark/repo-connectors/mock/mock-repo-connector.md +++ b/docs/verification/build-mark/repo-connectors/mock/mock-repo-connector.md @@ -1,21 +1,21 @@ -# MockRepoConnector +#### MockRepoConnector -## Verification Approach +##### Verification Approach `MockRepoConnector` is tested through `MockRepoConnectorTests.cs`, which contains 11 unit tests. The tests verify that the connector correctly returns in-memory data supplied via its configuration API, handles all routing and `HasRules` logic, and correctly implements all members of `IRepoConnector`. -## Dependencies +##### Dependencies | Mock / Stub | Reason | | ----------- | ---------------------------------- | | None | Self-contained in-memory connector | -## Test Scenarios +##### Test Scenarios -### MockRepoConnector_ImplementsInterface +###### MockRepoConnector_ImplementsInterface **Scenario**: `MockRepoConnector` is checked against `IRepoConnector`. @@ -23,7 +23,7 @@ correctly implements all members of `IRepoConnector`. **Requirement coverage**: `BuildMark-RepoConnectors-IRepoConnector` -### MockRepoConnector_Constructor_CreatesInstance +###### MockRepoConnector_Constructor_CreatesInstance **Scenario**: `MockRepoConnector` is constructed with no arguments. @@ -31,7 +31,7 @@ correctly implements all members of `IRepoConnector`. **Requirement coverage**: `BuildMark-RepoConnectors-Mock` -### MockRepoConnector_GetBuildInformationAsync_NoData_ReturnsEmptyBuildInformation +###### MockRepoConnector_GetBuildInformationAsync_NoData_ReturnsEmptyBuildInformation **Scenario**: `GetBuildInformationAsync` is called on an unconfigured connector. @@ -39,7 +39,7 @@ correctly implements all members of `IRepoConnector`. **Requirement coverage**: `BuildMark-RepoConnectors-Mock` -### MockRepoConnector_SetBuildVersion_StoresVersion +###### MockRepoConnector_SetBuildVersion_StoresVersion **Scenario**: `SetBuildVersion` is called with a version string. @@ -47,7 +47,7 @@ correctly implements all members of `IRepoConnector`. **Requirement coverage**: `BuildMark-RepoConnectors-Mock` -### MockRepoConnector_SetBaselineVersion_StoresBaseline +###### MockRepoConnector_SetBaselineVersion_StoresBaseline **Scenario**: `SetBaselineVersion` is called with a version string. @@ -55,7 +55,7 @@ correctly implements all members of `IRepoConnector`. **Requirement coverage**: `BuildMark-RepoConnectors-Mock` -### MockRepoConnector_AddChange_AddsItemToChanges +###### MockRepoConnector_AddChange_AddsItemToChanges **Scenario**: `AddChange` is called with a change item. @@ -63,7 +63,7 @@ correctly implements all members of `IRepoConnector`. **Requirement coverage**: `BuildMark-RepoConnectors-Mock` -### MockRepoConnector_AddKnownIssue_AddsItemToKnownIssues +###### MockRepoConnector_AddKnownIssue_AddsItemToKnownIssues **Scenario**: `AddKnownIssue` is called with a known issue item. @@ -71,7 +71,7 @@ correctly implements all members of `IRepoConnector`. **Requirement coverage**: `BuildMark-RepoConnectors-Mock` -### MockRepoConnector_Configure_WithRules_HasRulesReturnsTrue +###### MockRepoConnector_Configure_WithRules_HasRulesReturnsTrue **Scenario**: `Configure` is called with a non-empty rules list. @@ -79,7 +79,7 @@ correctly implements all members of `IRepoConnector`. **Requirement coverage**: `BuildMark-RepoConnectors-Mock` -### MockRepoConnector_Configure_EmptyRules_HasRulesReturnsFalse +###### MockRepoConnector_Configure_EmptyRules_HasRulesReturnsFalse **Scenario**: `Configure` is called with an empty rules list. @@ -87,7 +87,7 @@ correctly implements all members of `IRepoConnector`. **Requirement coverage**: `BuildMark-RepoConnectors-Mock` -### MockRepoConnector_GetBuildInformationAsync_WithConfiguredRules_PopulatesRoutedSections +###### MockRepoConnector_GetBuildInformationAsync_WithConfiguredRules_PopulatesRoutedSections **Scenario**: Connector is configured with routing rules; changes and known issues are added; `GetBuildInformationAsync` is called. @@ -96,7 +96,7 @@ added; `GetBuildInformationAsync` is called. **Requirement coverage**: `BuildMark-RepoConnectors-Mock` -### MockRepoConnector_GetBuildInformationAsync_WithChangelogLink_StoresLink +###### MockRepoConnector_GetBuildInformationAsync_WithChangelogLink_StoresLink **Scenario**: A changelog link is set on the connector. @@ -104,7 +104,7 @@ added; `GetBuildInformationAsync` is called. **Requirement coverage**: `BuildMark-RepoConnectors-Mock` -## Requirements Coverage +##### Requirements Coverage - **BuildMark-RepoConnectors-IRepoConnector**: MockRepoConnector_ImplementsInterface - **BuildMark-RepoConnectors-Mock**: All remaining 10 tests in `MockRepoConnectorTests.cs` diff --git a/docs/verification/build-mark/repo-connectors/repo-connector-base.md b/docs/verification/build-mark/repo-connectors/repo-connector-base.md index 5b2183e8..483cd265 100644 --- a/docs/verification/build-mark/repo-connectors/repo-connector-base.md +++ b/docs/verification/build-mark/repo-connectors/repo-connector-base.md @@ -1,21 +1,21 @@ -# RepoConnectorBase +### RepoConnectorBase -## Verification Approach +#### Verification Approach `RepoConnectorBase` is tested through `RepoConnectorBaseTests.cs`, which contains 5 unit tests. The tests exercise `Configure` (storing rules and sections and setting `HasRules`), `ApplyRules` (routing items to sections), and `FindVersionIndex` (locating a version tag in a list, including cross-prefix equality). -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ------------------------- | -------------------------------------------------------------- | | Concrete subclass fixture | Tests instantiate a minimal concrete subclass for testing base | -## Test Scenarios +#### Test Scenarios -### RepoConnectorBase_Configure_StoresRulesAndSections_HasRulesReturnsTrue +##### RepoConnectorBase_Configure_StoresRulesAndSections_HasRulesReturnsTrue **Scenario**: `Configure` is called with a non-empty rules list. @@ -23,7 +23,7 @@ a version tag in a list, including cross-prefix equality). **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorBase` -### RepoConnectorBase_Configure_EmptyRules_HasRulesReturnsFalse +##### RepoConnectorBase_Configure_EmptyRules_HasRulesReturnsFalse **Scenario**: `Configure` is called with an empty rules list. @@ -31,7 +31,7 @@ a version tag in a list, including cross-prefix equality). **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorBase` -### RepoConnectorBase_ApplyRules_RoutesItemsToConfiguredSections +##### RepoConnectorBase_ApplyRules_RoutesItemsToConfiguredSections **Scenario**: `ApplyRules` is called with items and configured routing rules. @@ -39,7 +39,7 @@ a version tag in a list, including cross-prefix equality). **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorBase` -### RepoConnectorBase_FindVersionIndex_DifferentPrefixSameVersion_ReturnsCorrectIndex +##### RepoConnectorBase_FindVersionIndex_DifferentPrefixSameVersion_ReturnsCorrectIndex **Scenario**: `FindVersionIndex` is called with a tag list containing a tag with a different prefix but the same version as the search target. @@ -48,7 +48,7 @@ different prefix but the same version as the search target. **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorBase` -### RepoConnectorBase_FindVersionIndex_VersionNotInList_ReturnsMinusOne +##### RepoConnectorBase_FindVersionIndex_VersionNotInList_ReturnsMinusOne **Scenario**: `FindVersionIndex` is called with a version that is not in the list. @@ -56,6 +56,6 @@ different prefix but the same version as the search target. **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorBase` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-RepoConnectors-RepoConnectorBase**: All 5 tests in `RepoConnectorBaseTests.cs` diff --git a/docs/verification/build-mark/repo-connectors/repo-connector-factory.md b/docs/verification/build-mark/repo-connectors/repo-connector-factory.md index f51ba6f9..7e83264d 100644 --- a/docs/verification/build-mark/repo-connectors/repo-connector-factory.md +++ b/docs/verification/build-mark/repo-connectors/repo-connector-factory.md @@ -1,22 +1,22 @@ -# RepoConnectorFactory +### RepoConnectorFactory -## Verification Approach +#### Verification Approach `RepoConnectorFactory` is tested through `RepoConnectorFactoryTests.cs`, which contains 11 unit tests. The tests cover connector creation from default settings, from explicit connector type configuration, from environment variables (GitHub Actions, Azure DevOps), and from remote URL detection. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ------------------------ | -------------------------------------------------------- | | Environment variables | Tests set/clear `GITHUB_ACTIONS` and `TF_BUILD` env vars | | Git remote URL (process) | Factory may invoke Git to detect the remote URL | -## Test Scenarios +#### Test Scenarios -### RepoConnectorFactory_Create_ReturnsConnector +##### RepoConnectorFactory_Create_ReturnsConnector **Scenario**: `RepoConnectorFactory.Create` is called with `null` configuration. @@ -24,7 +24,7 @@ and from remote URL detection. **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorFactory` -### RepoConnectorFactory_Create_ReturnsGitHubConnectorForThisRepo +##### RepoConnectorFactory_Create_ReturnsGitHubConnectorForThisRepo **Scenario**: Factory is invoked in the GitHub Actions CI environment. @@ -32,7 +32,7 @@ and from remote URL detection. **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorFactory` -### RepoConnectorFactory_Create_WithConnectorConfig_ForwardsGitHubConfiguration +##### RepoConnectorFactory_Create_WithConnectorConfig_ForwardsGitHubConfiguration **Scenario**: Factory is called with a `ConnectorConfig` specifying GitHub settings. @@ -40,7 +40,7 @@ and from remote URL detection. **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorFactory` -### RepoConnectorFactory_Create_WithAzureDevOpsType_CreatesAzureDevOpsConnector +##### RepoConnectorFactory_Create_WithAzureDevOpsType_CreatesAzureDevOpsConnector **Scenario**: Factory is called with `ConnectorConfig.Type = "azure-devops"`. @@ -48,7 +48,7 @@ and from remote URL detection. **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorFactory` -### RepoConnectorFactory_Create_WithAzureDevOpsConnectorConfig_ForwardsAzureDevOpsConfiguration +##### RepoConnectorFactory_Create_WithAzureDevOpsConnectorConfig_ForwardsAzureDevOpsConfiguration **Scenario**: Factory is called with Azure DevOps connector configuration. @@ -56,7 +56,7 @@ and from remote URL detection. **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorFactory` -### RepoConnectorFactory_Create_WithTfBuildEnv_ReturnsAzureDevOpsConnector +##### RepoConnectorFactory_Create_WithTfBuildEnv_ReturnsAzureDevOpsConnector **Scenario**: `TF_BUILD` environment variable is set to `"True"`. @@ -64,7 +64,7 @@ and from remote URL detection. **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorFactory` -### RepoConnectorFactory_Create_WithGitHubActionsEnv_ReturnsGitHubConnector +##### RepoConnectorFactory_Create_WithGitHubActionsEnv_ReturnsGitHubConnector **Scenario**: `GITHUB_ACTIONS` environment variable is set to `"true"`. @@ -72,7 +72,7 @@ and from remote URL detection. **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorFactory` -### RepoConnectorFactory_Create_WithAzureDevOpsRemoteUrl_ReturnsAzureDevOpsConnector +##### RepoConnectorFactory_Create_WithAzureDevOpsRemoteUrl_ReturnsAzureDevOpsConnector **Scenario**: Git remote URL matches an Azure DevOps `dev.azure.com` pattern. @@ -80,7 +80,7 @@ and from remote URL detection. **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorFactory` -### RepoConnectorFactory_Create_WithVisualStudioRemoteUrl_ReturnsAzureDevOpsConnector +##### RepoConnectorFactory_Create_WithVisualStudioRemoteUrl_ReturnsAzureDevOpsConnector **Scenario**: Git remote URL matches a `visualstudio.com` pattern. @@ -88,7 +88,7 @@ and from remote URL detection. **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorFactory` -### RepoConnectorFactory_Create_WithGitHubRemoteUrl_ReturnsGitHubConnector +##### RepoConnectorFactory_Create_WithGitHubRemoteUrl_ReturnsGitHubConnector **Scenario**: Git remote URL matches a `github.com` pattern. @@ -96,7 +96,7 @@ and from remote URL detection. **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorFactory` -### RepoConnectorFactory_Create_WithNullRemoteUrl_DefaultsToGitHubConnector +##### RepoConnectorFactory_Create_WithNullRemoteUrl_DefaultsToGitHubConnector **Scenario**: Git remote URL cannot be determined (null/empty). @@ -104,7 +104,7 @@ and from remote URL detection. **Requirement coverage**: `BuildMark-RepoConnectors-RepoConnectorFactory` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-RepoConnectors-RepoConnectorFactory**: All 11 tests in `RepoConnectorFactoryTests.cs` diff --git a/docs/verification/build-mark/self-test/self-test.md b/docs/verification/build-mark/self-test.md similarity index 85% rename from docs/verification/build-mark/self-test/self-test.md rename to docs/verification/build-mark/self-test.md index a097310e..a8f4a16e 100644 --- a/docs/verification/build-mark/self-test/self-test.md +++ b/docs/verification/build-mark/self-test.md @@ -1,21 +1,21 @@ -# SelfTest +## SelfTest -## Verification Approach +### Verification Approach The SelfTest subsystem is verified with dedicated subsystem tests in `SelfTestTests.cs`. Tests invoke `Validation.Run` through a `Context` constructed with controlled argument arrays, then inspect created results files and log output. `MockRepoConnector` is used so that no real repository access is needed. -## Dependencies +### Dependencies | Mock / Stub | Reason | | --- | --- | | `MockRepoConnector` | Provides a real connector factory that does not require external network access. | -## Test Scenarios +### Test Scenarios -### SelfTest_Validation_WithTrxFile_WritesResults +#### SelfTest_Validation_WithTrxFile_WritesResults **Scenario**: `Validation.Run` is called with `--validate --results .trx --silent`; the results file path ends in `.trx`. @@ -25,7 +25,7 @@ results file path ends in `.trx`. **Requirement coverage**: `BuildMark-SelfTest-Qualification`. -### SelfTest_Validation_WithXmlFile_WritesResults +#### SelfTest_Validation_WithXmlFile_WritesResults **Scenario**: `Validation.Run` is called with `--validate --results .xml --silent`; the results file path ends in `.xml`. @@ -35,7 +35,7 @@ results file path ends in `.xml`. **Requirement coverage**: `BuildMark-SelfTest-Qualification`. -### SelfTest_ResultsOutput_WithTrxFile_CreatesFile +#### SelfTest_ResultsOutput_WithTrxFile_CreatesFile **Scenario**: `Validation.Run` is called with `--validate --results output.trx --silent`. @@ -43,7 +43,7 @@ results file path ends in `.xml`. **Requirement coverage**: `BuildMark-SelfTest-ResultsOutput`. -### SelfTest_ResultsOutput_WithXmlFile_CreatesFile +#### SelfTest_ResultsOutput_WithXmlFile_CreatesFile **Scenario**: `Validation.Run` is called with `--validate --results output.xml --silent`. @@ -51,7 +51,7 @@ results file path ends in `.xml`. **Requirement coverage**: `BuildMark-SelfTest-ResultsOutput`. -### SelfTest_Qualification_WithoutResultsFile_Succeeds +#### SelfTest_Qualification_WithoutResultsFile_Succeeds **Scenario**: `Validation.Run` is called with `--validate --log /validation.log --silent`; no `--results` argument is supplied. @@ -61,7 +61,7 @@ results file path ends in `.xml`. **Requirement coverage**: `BuildMark-SelfTest-Qualification`. -## Requirements Coverage +### Requirements Coverage - **`BuildMark-SelfTest-Qualification`**: - SelfTest_Validation_WithTrxFile_WritesResults diff --git a/docs/verification/build-mark/self-test/validation.md b/docs/verification/build-mark/self-test/validation.md index 677cc987..6e53b7a3 100644 --- a/docs/verification/build-mark/self-test/validation.md +++ b/docs/verification/build-mark/self-test/validation.md @@ -1,21 +1,21 @@ -# Validation +### Validation -## Verification Approach +#### Verification Approach `Validation` is verified with dedicated unit tests in `ValidationTests.cs`. Tests construct a `Context` with controlled arguments, call `Validation.Run`, and assert on the created results files, console error output, and exit code. `MockRepoConnector` is provided as the connector factory; no further mocking is required. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ------------------- | --------------------------------------------------------------------- | | `MockRepoConnector` | Supplies connector factory so self-check runs without network access. | -## Test Scenarios +#### Test Scenarios -### Validation_Run_WithTrxResultsFile_WritesTrxFile +##### Validation_Run_WithTrxResultsFile_WritesTrxFile **Scenario**: `Validation.Run` is called with `--validate --results /results.trx`; console output is captured. @@ -25,7 +25,7 @@ output is captured. **Requirement coverage**: `BuildMark-Validation-Run`, `BuildMark-Validation-TrxOutput`. -### Validation_Run_WithXmlResultsFile_WritesJUnitFile +##### Validation_Run_WithXmlResultsFile_WritesJUnitFile **Scenario**: `Validation.Run` is called with `--validate --results /results.xml`; console output is captured. @@ -35,7 +35,7 @@ output is captured. **Requirement coverage**: `BuildMark-Validation-Run`, `BuildMark-Validation-JUnitOutput`. -### Validation_Run_WithUnsupportedResultsFileExtension_ShowsError +##### Validation_Run_WithUnsupportedResultsFileExtension_ShowsError **Scenario**: `Validation.Run` is called with `--validate --results /results.json` (unsupported extension); console error is captured. @@ -44,7 +44,7 @@ output is captured. **Requirement coverage**: `BuildMark-Validation-TrxOutput`, `BuildMark-Validation-JUnitOutput`. -### Validation_Run_WithInvalidResultsFilePath_ShowsError +##### Validation_Run_WithInvalidResultsFilePath_ShowsError **Scenario**: `Validation.Run` is called with `--validate --results /invalid_path_that_does_not_exist/results.trx`; console error is captured. @@ -53,7 +53,7 @@ output is captured. **Requirement coverage**: `BuildMark-Validation-TrxOutput`. -### Validation_Run_WithoutResultsFile_CompletesSuccessfully +##### Validation_Run_WithoutResultsFile_CompletesSuccessfully **Scenario**: `Validation.Run` is called with `--validate --silent`; no `--results` argument is supplied. @@ -62,7 +62,7 @@ supplied. **Requirement coverage**: `BuildMark-Validation-Run`. -## Requirements Coverage +#### Requirements Coverage - **`BuildMark-Validation-Run`**: - Validation_Run_WithTrxResultsFile_WritesTrxFile diff --git a/docs/verification/build-mark/utilities/utilities.md b/docs/verification/build-mark/utilities.md similarity index 81% rename from docs/verification/build-mark/utilities/utilities.md rename to docs/verification/build-mark/utilities.md index 47892ab3..9a576d7f 100644 --- a/docs/verification/build-mark/utilities/utilities.md +++ b/docs/verification/build-mark/utilities.md @@ -1,6 +1,6 @@ -# Utilities +## Utilities -## Verification Approach +### Verification Approach The Utilities subsystem is verified through `RepoConnectorsTests.cs` (for `ProcessRunner`) and indirectly through `CliTests.cs` (for `PathHelpers` via @@ -8,17 +8,17 @@ path-related flag handling). There is no dedicated `UtilitiesTests.cs` file; coverage is provided by integration-level tests that exercise the utility classes as they are used by other units. -## Dependencies +### Dependencies | Mock / Stub | Reason | | ------------- | --------------------------------------------------------------------- | | None required | `ProcessRunner` tests use real processes; `PathHelpers` is pure logic | -## Test Scenarios (Integration) +### Test Scenarios (Integration) The following integration tests in `RepoConnectorsTests.cs` exercise `ProcessRunner`: -### RepoConnectors_ProcessRunner_TryRunAsync_WithValidCommand_ReturnsOutput +#### RepoConnectors_ProcessRunner_TryRunAsync_WithValidCommand_ReturnsOutput **Scenario**: `ProcessRunner.TryRunAsync` is called with a valid system command. @@ -26,7 +26,7 @@ The following integration tests in `RepoConnectorsTests.cs` exercise `ProcessRun **Requirement coverage**: `BuildMark-Utilities-ProcessRunner` -### RepoConnectors_ProcessRunner_TryRunAsync_WithInvalidCommand_ReturnsNull +#### RepoConnectors_ProcessRunner_TryRunAsync_WithInvalidCommand_ReturnsNull **Scenario**: `ProcessRunner.TryRunAsync` is called with an invalid/nonexistent command. @@ -34,7 +34,7 @@ The following integration tests in `RepoConnectorsTests.cs` exercise `ProcessRun **Requirement coverage**: `BuildMark-Utilities-ProcessRunner` -### RepoConnectors_ProcessRunner_TryRunAsync_WithNonZeroExitCode_ReturnsNull +#### RepoConnectors_ProcessRunner_TryRunAsync_WithNonZeroExitCode_ReturnsNull **Scenario**: `ProcessRunner.TryRunAsync` is called with a command that exits non-zero. @@ -42,7 +42,7 @@ The following integration tests in `RepoConnectorsTests.cs` exercise `ProcessRun **Requirement coverage**: `BuildMark-Utilities-ProcessRunner` -### RepoConnectors_ProcessRunner_RunAsync_WithValidCommand_ReturnsOutput +#### RepoConnectors_ProcessRunner_RunAsync_WithValidCommand_ReturnsOutput **Scenario**: `ProcessRunner.RunAsync` is called with a valid command. @@ -50,7 +50,7 @@ The following integration tests in `RepoConnectorsTests.cs` exercise `ProcessRun **Requirement coverage**: `BuildMark-Utilities-ProcessRunner` -### RepoConnectors_ProcessRunner_RunAsync_WithFailingCommand_ThrowsException +#### RepoConnectors_ProcessRunner_RunAsync_WithFailingCommand_ThrowsException **Scenario**: `ProcessRunner.RunAsync` is called with a command that fails. @@ -58,7 +58,7 @@ The following integration tests in `RepoConnectorsTests.cs` exercise `ProcessRun **Requirement coverage**: `BuildMark-Utilities-ProcessRunner` -## Requirements Coverage +### Requirements Coverage - **BuildMark-Utilities-ProcessRunner**: RepoConnectors_ProcessRunner_TryRunAsync_WithValidCommand_ReturnsOutput, diff --git a/docs/verification/build-mark/utilities/path-helpers.md b/docs/verification/build-mark/utilities/path-helpers.md index 521740c7..60b2ece4 100644 --- a/docs/verification/build-mark/utilities/path-helpers.md +++ b/docs/verification/build-mark/utilities/path-helpers.md @@ -1,6 +1,6 @@ -# PathHelpers +### PathHelpers -## Verification Approach +#### Verification Approach `PathHelpers` is a pure utility class with no dedicated test class. It is verified indirectly through CLI and program tests that exercise path-related flag handling @@ -11,15 +11,15 @@ No direct unit tests exist for `PathHelpers` because the class provides straight path combination logic with no branching that requires isolated testing. Its behavior is validated through the integration tests that consume it. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | ---------- | | None | Pure logic | -## Test Scenarios (Integration) +#### Test Scenarios (Integration) -### Cli_LogFlag_CreatesLogFile +##### Cli_LogFlag_CreatesLogFile **Scenario**: `Context` is created with a log file path; `PathHelpers` is used to resolve the file path. @@ -28,7 +28,7 @@ resolve the file path. **Requirement coverage**: `BuildMark-Utilities-PathHelpers` -### Cli_ReportFlags_SetProperties +##### Cli_ReportFlags_SetProperties **Scenario**: `Context` is created with `--report` flag; path is processed by the context/utilities layer. @@ -37,7 +37,7 @@ context/utilities layer. **Requirement coverage**: `BuildMark-Utilities-PathHelpers` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-Utilities-PathHelpers**: Cli_LogFlag_CreatesLogFile, Cli_ReportFlags_SetProperties diff --git a/docs/verification/build-mark/utilities/process-runner.md b/docs/verification/build-mark/utilities/process-runner.md index 87c69e96..0cd62507 100644 --- a/docs/verification/build-mark/utilities/process-runner.md +++ b/docs/verification/build-mark/utilities/process-runner.md @@ -1,21 +1,21 @@ -# ProcessRunner +### ProcessRunner -## Verification Approach +#### Verification Approach `ProcessRunner` is tested through `RepoConnectorsTests.cs`. The five ProcessRunner tests exercise `TryRunAsync` (which returns `null` on failure) and `RunAsync` (which throws on failure) using real OS processes to confirm the process execution logic is correct on the target operating system. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | ----------------------------------------------------------- | | None | Real OS processes are used to test actual process execution | -## Test Scenarios +#### Test Scenarios -### RepoConnectors_ProcessRunner_TryRunAsync_WithValidCommand_ReturnsOutput +##### RepoConnectors_ProcessRunner_TryRunAsync_WithValidCommand_ReturnsOutput **Scenario**: `ProcessRunner.TryRunAsync` is called with a valid system command. @@ -23,7 +23,7 @@ correct on the target operating system. **Requirement coverage**: `BuildMark-Utilities-ProcessRunner` -### RepoConnectors_ProcessRunner_TryRunAsync_WithInvalidCommand_ReturnsNull +##### RepoConnectors_ProcessRunner_TryRunAsync_WithInvalidCommand_ReturnsNull **Scenario**: `ProcessRunner.TryRunAsync` is called with an invalid command name. @@ -31,7 +31,7 @@ correct on the target operating system. **Requirement coverage**: `BuildMark-Utilities-ProcessRunner` -### RepoConnectors_ProcessRunner_TryRunAsync_WithNonZeroExitCode_ReturnsNull +##### RepoConnectors_ProcessRunner_TryRunAsync_WithNonZeroExitCode_ReturnsNull **Scenario**: `ProcessRunner.TryRunAsync` is called with a command that exits with a non-zero code. @@ -40,7 +40,7 @@ a non-zero code. **Requirement coverage**: `BuildMark-Utilities-ProcessRunner` -### RepoConnectors_ProcessRunner_RunAsync_WithValidCommand_ReturnsOutput +##### RepoConnectors_ProcessRunner_RunAsync_WithValidCommand_ReturnsOutput **Scenario**: `ProcessRunner.RunAsync` is called with a valid command. @@ -48,7 +48,7 @@ a non-zero code. **Requirement coverage**: `BuildMark-Utilities-ProcessRunner` -### RepoConnectors_ProcessRunner_RunAsync_WithFailingCommand_ThrowsException +##### RepoConnectors_ProcessRunner_RunAsync_WithFailingCommand_ThrowsException **Scenario**: `ProcessRunner.RunAsync` is called with a command that returns a non-zero exit code. @@ -57,7 +57,7 @@ non-zero exit code. **Requirement coverage**: `BuildMark-Utilities-ProcessRunner` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-Utilities-ProcessRunner**: RepoConnectors_ProcessRunner_TryRunAsync_WithValidCommand_ReturnsOutput, diff --git a/docs/verification/build-mark/version/version.md b/docs/verification/build-mark/version.md similarity index 84% rename from docs/verification/build-mark/version/version.md rename to docs/verification/build-mark/version.md index bd5d0696..da6422a0 100644 --- a/docs/verification/build-mark/version/version.md +++ b/docs/verification/build-mark/version.md @@ -1,6 +1,6 @@ -# Version +## Version -## Verification Approach +### Verification Approach The Version subsystem is verified through `VersionTests.cs` (subsystem integration tests), plus dedicated unit test files for each version class. The subsystem tests @@ -8,15 +8,15 @@ exercise the interaction between version types - creating `VersionTag` instances extracting `VersionComparable`, and comparing via `VersionInterval`. The unit tests are described in the individual unit chapters. -## Dependencies +### Dependencies | Mock / Stub | Reason | | ----------- | ---------- | | None | Pure logic | -## Test Scenarios +### Test Scenarios -### VersionComparable_Create_ValidVersions_ReturnsVersionComparable +#### VersionComparable_Create_ValidVersions_ReturnsVersionComparable **Scenario**: `VersionComparable.Create` is called with a valid version string. @@ -24,7 +24,7 @@ are described in the individual unit chapters. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionSemantic_Create_ValidSemanticVersion_ReturnsVersionSemantic +#### VersionSemantic_Create_ValidSemanticVersion_ReturnsVersionSemantic **Scenario**: `VersionSemantic.Create` is called with a valid semantic version string. @@ -32,7 +32,7 @@ are described in the individual unit chapters. **Requirement coverage**: `BuildMark-Version-VersionSemantic` -### VersionTag_Create_ValidTag_ReturnsVersionTag +#### VersionTag_Create_ValidTag_ReturnsVersionTag **Scenario**: `VersionTag.Create` is called with a valid tag string. @@ -40,7 +40,7 @@ are described in the individual unit chapters. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionInterval_Create_ValidInterval_ReturnsVersionInterval +#### VersionInterval_Create_ValidInterval_ReturnsVersionInterval **Scenario**: `VersionInterval.Parse` is called with a valid interval string. @@ -48,7 +48,7 @@ are described in the individual unit chapters. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionCommitTag_Constructor_ValidParameters_CreatesInstance +#### VersionCommitTag_Constructor_ValidParameters_CreatesInstance **Scenario**: `VersionCommitTag` is constructed with a valid tag and commit hash. @@ -56,7 +56,7 @@ are described in the individual unit chapters. **Requirement coverage**: `BuildMark-Version-VersionCommitTag` -### Version_Subsystem_CreateAllVersionTypes_WorksCorrectly +#### Version_Subsystem_CreateAllVersionTypes_WorksCorrectly **Scenario**: All version type factory methods are invoked in sequence. @@ -65,7 +65,7 @@ are described in the individual unit chapters. **Requirement coverage**: `BuildMark-Version-VersionComparable`, `BuildMark-Version-VersionSemantic`, `BuildMark-Version-VersionTag` -### Version_Subsystem_SemanticVersioningCompliance_WorksCorrectly +#### Version_Subsystem_SemanticVersioningCompliance_WorksCorrectly **Scenario**: Version strings from the semver specification are parsed and compared. @@ -73,7 +73,7 @@ are described in the individual unit chapters. **Requirement coverage**: `BuildMark-Version-VersionComparable`, `BuildMark-Version-VersionSemantic` -### Version_Subsystem_TagToComparableIntegration_WorksCorrectly +#### Version_Subsystem_TagToComparableIntegration_WorksCorrectly **Scenario**: A `VersionTag` is created and its comparable representation is extracted. @@ -81,7 +81,7 @@ are described in the individual unit chapters. **Requirement coverage**: `BuildMark-Version-VersionTag`, `BuildMark-Version-VersionComparable` -## Requirements Coverage +### Requirements Coverage - **BuildMark-Version-VersionComparable**: VersionComparable_Create_ValidVersions_ReturnsVersionComparable, Version_Subsystem_CreateAllVersionTypes_WorksCorrectly, diff --git a/docs/verification/build-mark/version/version-commit-tag.md b/docs/verification/build-mark/version/version-commit-tag.md index 6877f777..5374f8d5 100644 --- a/docs/verification/build-mark/version/version-commit-tag.md +++ b/docs/verification/build-mark/version/version-commit-tag.md @@ -1,21 +1,21 @@ -# VersionCommitTag +### VersionCommitTag -## Verification Approach +#### Verification Approach `VersionCommitTag` is a simple data class with no dedicated test class. It is verified through `VersionTests.cs` via the test `VersionCommitTag_Constructor_ValidParameters_CreatesInstance`, which constructs an instance and asserts that the tag and commit-hash properties are stored correctly. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | ---------- | | None | Data class | -## Test Scenarios +#### Test Scenarios -### VersionCommitTag_Constructor_ValidParameters_CreatesInstance +##### VersionCommitTag_Constructor_ValidParameters_CreatesInstance **Scenario**: `VersionCommitTag` is constructed with a `VersionTag` and a commit hash string. @@ -24,6 +24,6 @@ string. **Requirement coverage**: `BuildMark-Version-VersionCommitTag` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-Version-VersionCommitTag**: VersionCommitTag_Constructor_ValidParameters_CreatesInstance diff --git a/docs/verification/build-mark/version/version-comparable.md b/docs/verification/build-mark/version/version-comparable.md index b142e7c6..ae3e9088 100644 --- a/docs/verification/build-mark/version/version-comparable.md +++ b/docs/verification/build-mark/version/version-comparable.md @@ -1,21 +1,21 @@ -# VersionComparable +### VersionComparable -## Verification Approach +#### Verification Approach `VersionComparable` is tested through `VersionComparableTests.cs`, which contains 26 unit tests. The tests cover creation (valid, invalid, null, empty), comparison operators, and numeric-vs-lexicographic pre-release ordering rules that follow the Semantic Versioning specification. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | ---------- | | None | Pure logic | -## Test Scenarios +#### Test Scenarios -### VersionComparable_Create_ValidVersion_ReturnsInstance +##### VersionComparable_Create_ValidVersion_ReturnsInstance **Scenario**: `VersionComparable.Create` is called with a valid version string. @@ -23,7 +23,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_Create_SimpleVersion_ParsesVersion +##### VersionComparable_Create_SimpleVersion_ParsesVersion **Scenario**: `VersionComparable.Create` is called with a simple `major.minor.patch` string. @@ -31,7 +31,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_Create_PreReleaseVersion_ParsesVersion +##### VersionComparable_Create_PreReleaseVersion_ParsesVersion **Scenario**: `VersionComparable.Create` is called with a pre-release version string. @@ -39,7 +39,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_TryCreate_InvalidVersion_ReturnsNull +##### VersionComparable_TryCreate_InvalidVersion_ReturnsNull **Scenario**: `VersionComparable.TryCreate` is called with an invalid version string. @@ -47,7 +47,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_TryCreate_NullInput_ReturnsNull +##### VersionComparable_TryCreate_NullInput_ReturnsNull **Scenario**: `VersionComparable.TryCreate` is called with a `null` argument. @@ -55,7 +55,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_TryCreate_EmptyInput_ReturnsNull +##### VersionComparable_TryCreate_EmptyInput_ReturnsNull **Scenario**: `VersionComparable.TryCreate` is called with an empty string. @@ -63,7 +63,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_Create_InvalidVersion_ThrowsArgumentException +##### VersionComparable_Create_InvalidVersion_ThrowsArgumentException **Scenario**: `VersionComparable.Create` is called with an invalid version string. @@ -71,7 +71,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_CompareTo_SameMajorMinorPatch_ReturnsZero +##### VersionComparable_CompareTo_SameMajorMinorPatch_ReturnsZero **Scenario**: Two instances with identical major.minor.patch are compared. @@ -79,7 +79,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_CompareTo_DifferentMajor_ReturnsCorrectOrder +##### VersionComparable_CompareTo_DifferentMajor_ReturnsCorrectOrder **Scenario**: Two instances with different major versions are compared. @@ -87,7 +87,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_CompareTo_DifferentMinor_ReturnsCorrectOrder +##### VersionComparable_CompareTo_DifferentMinor_ReturnsCorrectOrder **Scenario**: Two instances with different minor versions are compared. @@ -95,7 +95,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_CompareTo_DifferentPatch_ReturnsCorrectOrder +##### VersionComparable_CompareTo_DifferentPatch_ReturnsCorrectOrder **Scenario**: Two instances with different patch versions are compared. @@ -103,7 +103,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_CompareTo_PreReleaseVsRelease_ReturnsCorrectOrder +##### VersionComparable_CompareTo_PreReleaseVsRelease_ReturnsCorrectOrder **Scenario**: A pre-release version is compared to its release counterpart. @@ -111,7 +111,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_CompareTo_PreReleaseVersions_ReturnsLexicographicOrder +##### VersionComparable_CompareTo_PreReleaseVersions_ReturnsLexicographicOrder **Scenario**: Two pre-release versions with non-numeric identifiers are compared. @@ -119,7 +119,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_Operators_LessThan_WorksCorrectly +##### VersionComparable_Operators_LessThan_WorksCorrectly **Scenario**: The `<` operator is applied to two version instances. @@ -127,7 +127,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_Operators_GreaterThan_WorksCorrectly +##### VersionComparable_Operators_GreaterThan_WorksCorrectly **Scenario**: The `>` operator is applied to two version instances. @@ -135,7 +135,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_Operators_LessThanOrEqual_WorksCorrectly +##### VersionComparable_Operators_LessThanOrEqual_WorksCorrectly **Scenario**: The `<=` operator is applied to two version instances. @@ -143,7 +143,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_Operators_GreaterThanOrEqual_WorksCorrectly +##### VersionComparable_Operators_GreaterThanOrEqual_WorksCorrectly **Scenario**: The `>=` operator is applied to two version instances. @@ -151,7 +151,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_CompareTo_SemanticVersions_ReturnsCorrectOrder +##### VersionComparable_CompareTo_SemanticVersions_ReturnsCorrectOrder **Scenario**: A series of semver-compliant versions is compared. @@ -159,7 +159,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_CompareTo_NumericComparison_CorrectOrdering +##### VersionComparable_CompareTo_NumericComparison_CorrectOrdering **Scenario**: Numeric pre-release identifiers are compared. @@ -167,7 +167,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_CompareTo_ReleaseGreaterThanPreRelease_CorrectOrdering +##### VersionComparable_CompareTo_ReleaseGreaterThanPreRelease_CorrectOrdering **Scenario**: Release version `1.0.0` is compared to `1.0.0-alpha`. @@ -175,7 +175,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_CompareTo_PreReleaseLexicographic_CorrectOrdering +##### VersionComparable_CompareTo_PreReleaseLexicographic_CorrectOrdering **Scenario**: Pre-release identifiers with alphabetic content are compared. @@ -183,7 +183,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_CompareTo_PreReleaseNumeric_ComparesNumerically +##### VersionComparable_CompareTo_PreReleaseNumeric_ComparesNumerically **Scenario**: Pre-release identifiers that are purely numeric are compared. @@ -191,7 +191,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_CompareTo_PreReleaseSemVerRules_CorrectOrdering +##### VersionComparable_CompareTo_PreReleaseSemVerRules_CorrectOrdering **Scenario**: Pre-release versions are compared following all semver rules. @@ -199,7 +199,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_CompareTo_NumericVsNonNumeric_NumericIsLess +##### VersionComparable_CompareTo_NumericVsNonNumeric_NumericIsLess **Scenario**: A numeric pre-release identifier is compared to a non-numeric one. @@ -207,7 +207,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_CompareTo_ShorterPreRelease_IsLess +##### VersionComparable_CompareTo_ShorterPreRelease_IsLess **Scenario**: Two pre-release versions with different numbers of identifiers are compared. @@ -215,7 +215,7 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -### VersionComparable_CompareTo_ComplexPreRelease_CorrectOrdering +##### VersionComparable_CompareTo_ComplexPreRelease_CorrectOrdering **Scenario**: Complex multi-identifier pre-release versions are compared. @@ -223,6 +223,6 @@ Semantic Versioning specification. **Requirement coverage**: `BuildMark-Version-VersionComparable` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-Version-VersionComparable**: All 26 tests in `VersionComparableTests.cs` diff --git a/docs/verification/build-mark/version/version-interval-set.md b/docs/verification/build-mark/version/version-interval-set.md index 6670f407..5c7aa144 100644 --- a/docs/verification/build-mark/version/version-interval-set.md +++ b/docs/verification/build-mark/version/version-interval-set.md @@ -1,6 +1,6 @@ -# VersionIntervalSet +### VersionIntervalSet -## Verification Approach +#### Verification Approach `VersionIntervalSet` is tested through `VersionIntervalSetTests.cs`, which contains 13 unit tests. The tests cover parsing single and multiple intervals, handling of @@ -8,15 +8,15 @@ internal commas in interval strings, empty input, discarding invalid tokens, and `Contains` checks for strings, `VersionTag` instances, pre-release versions, and `VersionComparable` instances. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | ---------- | | None | Pure logic | -## Test Scenarios +#### Test Scenarios -### VersionIntervalSet_Parse_SingleInterval_ReturnsOneInterval +##### VersionIntervalSet_Parse_SingleInterval_ReturnsOneInterval **Scenario**: `VersionIntervalSet.Parse` is called with a single interval string. @@ -24,7 +24,7 @@ internal commas in interval strings, empty input, discarding invalid tokens, and **Requirement coverage**: `BuildMark-Version-VersionIntervalSet` -### VersionIntervalSet_Parse_TwoIntervals_ReturnsTwoIntervals +##### VersionIntervalSet_Parse_TwoIntervals_ReturnsTwoIntervals **Scenario**: `VersionIntervalSet.Parse` is called with two comma-separated intervals. @@ -32,7 +32,7 @@ internal commas in interval strings, empty input, discarding invalid tokens, and **Requirement coverage**: `BuildMark-Version-VersionIntervalSet` -### VersionIntervalSet_Parse_IntervalsWithInternalComma_ParsedCorrectly +##### VersionIntervalSet_Parse_IntervalsWithInternalComma_ParsedCorrectly **Scenario**: `VersionIntervalSet.Parse` is called with an interval string that contains a comma as the separator between lower and upper bound. @@ -41,7 +41,7 @@ contains a comma as the separator between lower and upper bound. **Requirement coverage**: `BuildMark-Version-VersionIntervalSet` -### VersionIntervalSet_Parse_EmptyString_ReturnsEmptySet +##### VersionIntervalSet_Parse_EmptyString_ReturnsEmptySet **Scenario**: `VersionIntervalSet.Parse` is called with an empty string. @@ -49,7 +49,7 @@ contains a comma as the separator between lower and upper bound. **Requirement coverage**: `BuildMark-Version-VersionIntervalSet` -### VersionIntervalSet_Parse_InvalidToken_DiscardedSilently +##### VersionIntervalSet_Parse_InvalidToken_DiscardedSilently **Scenario**: `VersionIntervalSet.Parse` is called with a string containing invalid tokens mixed with valid intervals. @@ -58,7 +58,7 @@ tokens mixed with valid intervals. **Requirement coverage**: `BuildMark-Version-VersionIntervalSet` -### VersionIntervalSet_Contains_StringInsideFirstInterval_ReturnsTrue +##### VersionIntervalSet_Contains_StringInsideFirstInterval_ReturnsTrue **Scenario**: `Contains` is called with a string version inside the first interval. @@ -66,7 +66,7 @@ tokens mixed with valid intervals. **Requirement coverage**: `BuildMark-Version-VersionIntervalSet` -### VersionIntervalSet_Contains_StringInsideLaterInterval_ReturnsTrue +##### VersionIntervalSet_Contains_StringInsideLaterInterval_ReturnsTrue **Scenario**: `Contains` is called with a string version inside a later interval. @@ -74,7 +74,7 @@ tokens mixed with valid intervals. **Requirement coverage**: `BuildMark-Version-VersionIntervalSet` -### VersionIntervalSet_Contains_StringOutsideAllIntervals_ReturnsFalse +##### VersionIntervalSet_Contains_StringOutsideAllIntervals_ReturnsFalse **Scenario**: `Contains` is called with a string version outside all intervals. @@ -82,7 +82,7 @@ tokens mixed with valid intervals. **Requirement coverage**: `BuildMark-Version-VersionIntervalSet` -### VersionIntervalSet_Contains_EmptySet_ReturnsFalse +##### VersionIntervalSet_Contains_EmptySet_ReturnsFalse **Scenario**: `Contains` is called on an empty set. @@ -90,7 +90,7 @@ tokens mixed with valid intervals. **Requirement coverage**: `BuildMark-Version-VersionIntervalSet` -### VersionIntervalSet_Contains_VersionTag_DelegatesToSemanticVersion +##### VersionIntervalSet_Contains_VersionTag_DelegatesToSemanticVersion **Scenario**: `Contains` is called with a `VersionTag` argument. @@ -98,7 +98,7 @@ tokens mixed with valid intervals. **Requirement coverage**: `BuildMark-Version-VersionIntervalSet` -### VersionIntervalSet_Contains_PreReleaseVersions_HandlesCorrectly +##### VersionIntervalSet_Contains_PreReleaseVersions_HandlesCorrectly **Scenario**: `Contains` is called with pre-release version strings. @@ -106,7 +106,7 @@ tokens mixed with valid intervals. **Requirement coverage**: `BuildMark-Version-VersionIntervalSet` -### VersionIntervalSet_Contains_VersionComparable_HandlesPreRelease +##### VersionIntervalSet_Contains_VersionComparable_HandlesPreRelease **Scenario**: `Contains` is called with a `VersionComparable` that has pre-release. @@ -114,7 +114,7 @@ tokens mixed with valid intervals. **Requirement coverage**: `BuildMark-Version-VersionIntervalSet` -### VersionIntervalSet_Parse_PreReleaseBounds_ParsesCorrectly +##### VersionIntervalSet_Parse_PreReleaseBounds_ParsesCorrectly **Scenario**: `VersionIntervalSet.Parse` is called with intervals using pre-release version bounds. @@ -123,6 +123,6 @@ version bounds. **Requirement coverage**: `BuildMark-Version-VersionIntervalSet` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-Version-VersionIntervalSet**: All 13 tests in `VersionIntervalSetTests.cs` diff --git a/docs/verification/build-mark/version/version-interval.md b/docs/verification/build-mark/version/version-interval.md index d4c6226e..39874a09 100644 --- a/docs/verification/build-mark/version/version-interval.md +++ b/docs/verification/build-mark/version/version-interval.md @@ -1,21 +1,21 @@ -# VersionInterval +### VersionInterval -## Verification Approach +#### Verification Approach `VersionInterval` is tested through `VersionIntervalTests.cs`, which contains 21 unit tests. The tests cover parsing of inclusive and exclusive lower/upper bounds, unbounded intervals, invalid input handling, and `Contains` checks for string versions, semantic versions, and pre-release versions. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | ---------- | | None | Pure logic | -## Test Scenarios +#### Test Scenarios -### VersionInterval_Parse_InclusiveLower_IsInclusive +##### VersionInterval_Parse_InclusiveLower_IsInclusive **Scenario**: `VersionInterval.Parse` is called with `[1.0.0,2.0.0]`. @@ -23,7 +23,7 @@ versions, and pre-release versions. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Parse_ExclusiveLower_IsExclusive +##### VersionInterval_Parse_ExclusiveLower_IsExclusive **Scenario**: `VersionInterval.Parse` is called with `(1.0.0,2.0.0)`. @@ -31,7 +31,7 @@ versions, and pre-release versions. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Parse_InclusiveUpper_IsInclusive +##### VersionInterval_Parse_InclusiveUpper_IsInclusive **Scenario**: `VersionInterval.Parse` is called with an interval using `]` upper bracket. @@ -39,7 +39,7 @@ versions, and pre-release versions. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Parse_ExclusiveUpper_IsExclusive +##### VersionInterval_Parse_ExclusiveUpper_IsExclusive **Scenario**: `VersionInterval.Parse` is called with an interval using `)` upper bracket. @@ -47,7 +47,7 @@ versions, and pre-release versions. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Parse_UnboundedLower_HasNullLowerBound +##### VersionInterval_Parse_UnboundedLower_HasNullLowerBound **Scenario**: `VersionInterval.Parse` is called with `(,2.0.0)` (no lower bound). @@ -55,7 +55,7 @@ versions, and pre-release versions. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Parse_UnboundedUpper_HasNullUpperBound +##### VersionInterval_Parse_UnboundedUpper_HasNullUpperBound **Scenario**: `VersionInterval.Parse` is called with `[1.0.0,)` (no upper bound). @@ -63,7 +63,7 @@ versions, and pre-release versions. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Parse_BothBoundsPresent_ReturnsInterval +##### VersionInterval_Parse_BothBoundsPresent_ReturnsInterval **Scenario**: `VersionInterval.Parse` is called with a fully bounded interval. @@ -71,7 +71,7 @@ versions, and pre-release versions. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Parse_InvalidFormat_ReturnsNull +##### VersionInterval_Parse_InvalidFormat_ReturnsNull **Scenario**: `VersionInterval.Parse` is called with a string that does not match the interval format. @@ -80,7 +80,7 @@ the interval format. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Parse_NullInput_ReturnsNull +##### VersionInterval_Parse_NullInput_ReturnsNull **Scenario**: `VersionInterval.Parse` is called with `null`. @@ -88,7 +88,7 @@ the interval format. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Parse_EmptyString_ReturnsNull +##### VersionInterval_Parse_EmptyString_ReturnsNull **Scenario**: `VersionInterval.Parse` is called with an empty string. @@ -96,7 +96,7 @@ the interval format. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Contains_StringEqualToInclusiveLower_ReturnsTrue +##### VersionInterval_Contains_StringEqualToInclusiveLower_ReturnsTrue **Scenario**: `Contains` is called with a string equal to the inclusive lower bound. @@ -104,7 +104,7 @@ the interval format. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Contains_StringEqualToExclusiveLower_ReturnsFalse +##### VersionInterval_Contains_StringEqualToExclusiveLower_ReturnsFalse **Scenario**: `Contains` is called with a string equal to the exclusive lower bound. @@ -112,7 +112,7 @@ the interval format. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Contains_StringEqualToInclusiveUpper_ReturnsTrue +##### VersionInterval_Contains_StringEqualToInclusiveUpper_ReturnsTrue **Scenario**: `Contains` is called with a string equal to the inclusive upper bound. @@ -120,7 +120,7 @@ the interval format. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Contains_StringEqualToExclusiveUpper_ReturnsFalse +##### VersionInterval_Contains_StringEqualToExclusiveUpper_ReturnsFalse **Scenario**: `Contains` is called with a string equal to the exclusive upper bound. @@ -128,7 +128,7 @@ the interval format. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Contains_StringInsideUnboundedInterval_ReturnsTrue +##### VersionInterval_Contains_StringInsideUnboundedInterval_ReturnsTrue **Scenario**: `Contains` is called with a version inside an unbounded interval. @@ -136,7 +136,7 @@ the interval format. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Contains_StringOutsideInterval_ReturnsFalse +##### VersionInterval_Contains_StringOutsideInterval_ReturnsFalse **Scenario**: `Contains` is called with a version outside the interval bounds. @@ -144,7 +144,7 @@ the interval format. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Contains_Version_DelegatesToSemanticVersion +##### VersionInterval_Contains_Version_DelegatesToSemanticVersion **Scenario**: `Contains` is called with a `VersionSemantic` argument. @@ -152,7 +152,7 @@ the interval format. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Contains_PreReleaseBounds_HandlesCorrectly +##### VersionInterval_Contains_PreReleaseBounds_HandlesCorrectly **Scenario**: An interval with pre-release bounds is created; `Contains` is called with a pre-release version. @@ -161,7 +161,7 @@ with a pre-release version. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Contains_PreReleaseToPreRelease_HandlesCorrectly +##### VersionInterval_Contains_PreReleaseToPreRelease_HandlesCorrectly **Scenario**: An interval spanning two pre-release versions; `Contains` checks a version between them. @@ -170,7 +170,7 @@ version between them. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Contains_PreReleaseOrdering_UsesNumericComparison +##### VersionInterval_Contains_PreReleaseOrdering_UsesNumericComparison **Scenario**: Interval bounds use numeric pre-release identifiers; `Contains` is called with intermediate numeric pre-releases. @@ -179,7 +179,7 @@ called with intermediate numeric pre-releases. **Requirement coverage**: `BuildMark-Version-VersionInterval` -### VersionInterval_Contains_VersionComparable_HandlesPreRelease +##### VersionInterval_Contains_VersionComparable_HandlesPreRelease **Scenario**: `Contains` is called with a `VersionComparable` that has a pre-release. @@ -187,6 +187,6 @@ called with intermediate numeric pre-releases. **Requirement coverage**: `BuildMark-Version-VersionInterval` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-Version-VersionInterval**: All 21 tests in `VersionIntervalTests.cs` diff --git a/docs/verification/build-mark/version/version-semantic.md b/docs/verification/build-mark/version/version-semantic.md index 5cb37ef1..fa8e4b72 100644 --- a/docs/verification/build-mark/version/version-semantic.md +++ b/docs/verification/build-mark/version/version-semantic.md @@ -1,20 +1,20 @@ -# VersionSemantic +### VersionSemantic -## Verification Approach +#### Verification Approach `VersionSemantic` is tested through `VersionSemanticTests.cs`, which contains 12 unit tests. The tests cover creation with and without build metadata, property delegation to the underlying `VersionComparable`, string formatting, and comparison. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | ---------- | | None | Pure logic | -## Test Scenarios +#### Test Scenarios -### VersionSemantic_Create_WithBuildMetadata_ReturnsInstance +##### VersionSemantic_Create_WithBuildMetadata_ReturnsInstance **Scenario**: `VersionSemantic.Create` is called with `"1.2.3+build.123"`. @@ -22,7 +22,7 @@ to the underlying `VersionComparable`, string formatting, and comparison. **Requirement coverage**: `BuildMark-Version-VersionSemantic` -### VersionSemantic_Create_WithoutBuildMetadata_ReturnsInstance +##### VersionSemantic_Create_WithoutBuildMetadata_ReturnsInstance **Scenario**: `VersionSemantic.Create` is called with `"1.2.3"`. @@ -30,7 +30,7 @@ to the underlying `VersionComparable`, string formatting, and comparison. **Requirement coverage**: `BuildMark-Version-VersionSemantic` -### VersionSemantic_Properties_DelegateToComparable_Correctly +##### VersionSemantic_Properties_DelegateToComparable_Correctly **Scenario**: `VersionSemantic.Create` is called with `"1.2.3-alpha"` and the `Major`, `Minor`, `Patch`, `PreRelease`, and `CompareVersion` properties are read. @@ -40,7 +40,7 @@ to the underlying `VersionComparable`, string formatting, and comparison. **Requirement coverage**: `BuildMark-Version-VersionSemantic` -### VersionSemantic_ToString_FormatsCompletely_WithAllComponents +##### VersionSemantic_ToString_FormatsCompletely_WithAllComponents **Scenario**: `VersionSemantic.Create` is called with `"1.2.3-alpha+build.123"` and `FullVersion` is read. @@ -49,7 +49,7 @@ to the underlying `VersionComparable`, string formatting, and comparison. **Requirement coverage**: `BuildMark-Version-VersionSemantic` -### VersionSemantic_PreRelease_ReturnsEmptyStringForRelease +##### VersionSemantic_PreRelease_ReturnsEmptyStringForRelease **Scenario**: `PreRelease` property is accessed on a release version (no `-` suffix). @@ -57,7 +57,7 @@ to the underlying `VersionComparable`, string formatting, and comparison. **Requirement coverage**: `BuildMark-Version-VersionSemantic` -### VersionSemantic_Parse_ValidSemanticVersions_ParsesCorrectly +##### VersionSemantic_Parse_ValidSemanticVersions_ParsesCorrectly **Scenario**: A series of standard semver strings are parsed. @@ -65,7 +65,7 @@ to the underlying `VersionComparable`, string formatting, and comparison. **Requirement coverage**: `BuildMark-Version-VersionSemantic` -### VersionSemantic_Create_SimpleVersion_ParsesVersion +##### VersionSemantic_Create_SimpleVersion_ParsesVersion **Scenario**: `VersionSemantic.Create` is called with `"1.2.3"`. @@ -75,7 +75,7 @@ to the underlying `VersionComparable`, string formatting, and comparison. **Requirement coverage**: `BuildMark-Version-VersionSemantic` -### VersionSemantic_Create_VersionWithMetadata_ParsesVersion +##### VersionSemantic_Create_VersionWithMetadata_ParsesVersion **Scenario**: `VersionSemantic.Create` is called with `"1.2.3+build.5"`. @@ -85,7 +85,7 @@ to the underlying `VersionComparable`, string formatting, and comparison. **Requirement coverage**: `BuildMark-Version-VersionSemantic` -### VersionSemantic_Create_PreReleaseWithMetadata_ParsesVersion +##### VersionSemantic_Create_PreReleaseWithMetadata_ParsesVersion **Scenario**: `VersionSemantic.Create` is called with `"2.0.0-alpha.1+linux.x64"`. @@ -95,7 +95,7 @@ equals `"linux.x64"`; `CompareVersion` equals `"2.0.0-alpha.1"`; `FullVersion` e **Requirement coverage**: `BuildMark-Version-VersionSemantic` -### VersionSemantic_TryCreate_InvalidVersion_ReturnsNull +##### VersionSemantic_TryCreate_InvalidVersion_ReturnsNull **Scenario**: `VersionSemantic.TryCreate` is called with `"not-a-version"`. @@ -103,7 +103,7 @@ equals `"linux.x64"`; `CompareVersion` equals `"2.0.0-alpha.1"`; `FullVersion` e **Requirement coverage**: `BuildMark-Version-VersionSemantic` -### VersionSemantic_Create_InvalidVersion_ThrowsArgumentException +##### VersionSemantic_Create_InvalidVersion_ThrowsArgumentException **Scenario**: `VersionSemantic.Create` is called with `"not-a-version"`. @@ -112,7 +112,7 @@ equals `"linux.x64"`; `CompareVersion` equals `"2.0.0-alpha.1"`; `FullVersion` e **Requirement coverage**: `BuildMark-Version-VersionSemantic` -### VersionSemantic_Comparable_AllowsComparison +##### VersionSemantic_Comparable_AllowsComparison **Scenario**: `Comparable` is compared for `"1.2.3+build1"` and `"1.2.4+build2"`. @@ -121,6 +121,6 @@ before `"1.2.4"`). **Requirement coverage**: `BuildMark-Version-VersionSemantic` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-Version-VersionSemantic**: All 12 tests in `VersionSemanticTests.cs` diff --git a/docs/verification/build-mark/version/version-tag.md b/docs/verification/build-mark/version/version-tag.md index 82646789..589d0c58 100644 --- a/docs/verification/build-mark/version/version-tag.md +++ b/docs/verification/build-mark/version/version-tag.md @@ -1,21 +1,21 @@ -# VersionTag +### VersionTag -## Verification Approach +#### Verification Approach `VersionTag` is tested through `VersionTagTests.cs`, which contains 19 unit tests. The tests cover parsing of standard tags, prefixed tags (e.g., `v1.2.3`), path-prefix tags (e.g., `mylib/1.2.3`), pre-release normalization (dots converted to hyphens), and error handling for invalid tags. -## Dependencies +#### Dependencies | Mock / Stub | Reason | | ----------- | ---------- | | None | Pure logic | -## Test Scenarios +#### Test Scenarios -### VersionTag_Create_ValidTag_ReturnsVersionTag +##### VersionTag_Create_ValidTag_ReturnsVersionTag **Scenario**: `VersionTag.Create` is called with a valid tag string. @@ -23,7 +23,7 @@ and error handling for invalid tags. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionTag_Create_StandardTag_ParsesCorrectly +##### VersionTag_Create_StandardTag_ParsesCorrectly **Scenario**: `VersionTag.Create` is called with `"1.2.3"` (no prefix). @@ -31,7 +31,7 @@ and error handling for invalid tags. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionTag_Create_PrefixedTag_ParsesCorrectly +##### VersionTag_Create_PrefixedTag_ParsesCorrectly **Scenario**: `VersionTag.Create` is called with `"v1.2.3"`. @@ -39,7 +39,7 @@ and error handling for invalid tags. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionTag_Create_DotSeparatedPreRelease_NormalizesToHyphen +##### VersionTag_Create_DotSeparatedPreRelease_NormalizesToHyphen **Scenario**: `VersionTag.Create` is called with `"v1.2.3.alpha.1"`. @@ -48,7 +48,7 @@ and error handling for invalid tags. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionTag_Create_ComplexTag_ExtractsVersionCorrectly +##### VersionTag_Create_ComplexTag_ExtractsVersionCorrectly **Scenario**: `VersionTag.Create` is called with `"Release_1.2.3.beta.5+build.123"`. @@ -58,7 +58,7 @@ and error handling for invalid tags. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionTag_Properties_ExposeOriginalAndParsed_Correctly +##### VersionTag_Properties_ExposeOriginalAndParsed_Correctly **Scenario**: `VersionTag.Create` is called with `"v1.2.3-alpha"` and the `Tag`, `FullVersion`, `Numbers`, and `PreRelease` properties are read. @@ -68,7 +68,7 @@ and error handling for invalid tags. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionTag_ToString_ReturnsOriginalTag +##### VersionTag_ToString_ReturnsOriginalTag **Scenario**: `ToString` is called on a `VersionTag` created from `"v1.2.3-alpha+build.123"`. @@ -76,7 +76,7 @@ and error handling for invalid tags. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionTag_Create_SimpleVPrefix_ParsesVersion +##### VersionTag_Create_SimpleVPrefix_ParsesVersion **Scenario**: `VersionTag.Create` is called with `"v1.2.3"`. @@ -86,7 +86,7 @@ and error handling for invalid tags. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionTag_Create_ComplexVersionWithMetadata_ParsesVersion +##### VersionTag_Create_ComplexVersionWithMetadata_ParsesVersion **Scenario**: `VersionTag.Create` is called with `"Rel_1.2.3.rc.4+build.5"`. @@ -97,7 +97,7 @@ is true. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionTag_TryCreate_InvalidTag_ReturnsNull +##### VersionTag_TryCreate_InvalidTag_ReturnsNull **Scenario**: `VersionTag.TryCreate` is called with `"not-a-version"`. @@ -105,7 +105,7 @@ is true. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionTag_Create_InvalidTag_ThrowsArgumentException +##### VersionTag_Create_InvalidTag_ThrowsArgumentException **Scenario**: `VersionTag.Create` is called with `"not-a-version"`. @@ -114,7 +114,7 @@ is true. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionTag_Create_NoPrefix_ParsesVersion +##### VersionTag_Create_NoPrefix_ParsesVersion **Scenario**: `VersionTag.Create` is called with `"1.0.0"`. @@ -122,7 +122,7 @@ is true. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionTag_Create_HyphenPreReleaseWithMetadata_ParsesVersion +##### VersionTag_Create_HyphenPreReleaseWithMetadata_ParsesVersion **Scenario**: `VersionTag.Create` is called with `"Rel_1.2.3-rc.4+build.5"`. @@ -133,7 +133,7 @@ is true. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionTag_Semantic_AllowsComparison +##### VersionTag_Semantic_AllowsComparison **Scenario**: `Semantic.Comparable` is compared for tags `"v1.2.3"` and `"v1.11.2"`. @@ -142,7 +142,7 @@ is true. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionComparable_Equals_DifferentPrefixesSameVersion_ReturnsTrue +##### VersionComparable_Equals_DifferentPrefixesSameVersion_ReturnsTrue **Scenario**: `Semantic.Comparable` is extracted from `"v1.2.3"`, `"VER1.2.3"`, `"Release_1.2.3"`, and `"release/1.2.3"` and the four values are compared for equality. @@ -151,7 +151,7 @@ is true. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionTag_GetVersionComparable_SemanticTags_ReturnsCorrectComparison +##### VersionTag_GetVersionComparable_SemanticTags_ReturnsCorrectComparison **Scenario**: `Semantic.Comparable` is compared for `"v1.0.0-alpha"`, `"v1.0.0-beta"`, and `"v1.0.0"`. @@ -161,7 +161,7 @@ which sorts before `"v1.0.0"`. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionTag_Create_PathSeparatorPrefix_ParsesCorrectly +##### VersionTag_Create_PathSeparatorPrefix_ParsesCorrectly **Scenario**: `VersionTag.Create` is called with `"release/1.2.3"`. @@ -170,7 +170,7 @@ equals `"1.2.3"`; `PreRelease` equals `""`; `IsPreRelease` is false. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionTag_Create_PathSeparatorPrefixWithPreRelease_ParsesCorrectly +##### VersionTag_Create_PathSeparatorPrefixWithPreRelease_ParsesCorrectly **Scenario**: `VersionTag.Create` is called with `"release/1.2.3-rc.4"`. @@ -180,7 +180,7 @@ equals `"1.2.3"`; `PreRelease` equals `""`; `IsPreRelease` is false. **Requirement coverage**: `BuildMark-Version-VersionTag` -### VersionTag_Create_MultiLevelPathPrefix_ParsesCorrectly +##### VersionTag_Create_MultiLevelPathPrefix_ParsesCorrectly **Scenario**: `VersionTag.Create` is called with `"builds/release/1.2.3-beta.1+build.99"`. @@ -190,6 +190,6 @@ equals `"1.2.3"`; `PreRelease` equals `""`; `IsPreRelease` is false. **Requirement coverage**: `BuildMark-Version-VersionTag` -## Requirements Coverage +#### Requirements Coverage - **BuildMark-Version-VersionTag**: All 19 tests in `VersionTagTests.cs` diff --git a/docs/verification/definition.yaml b/docs/verification/definition.yaml index be106081..9d71f2e2 100644 --- a/docs/verification/definition.yaml +++ b/docs/verification/definition.yaml @@ -10,7 +10,7 @@ resource-path: - docs/verification/build-mark/configuration - docs/verification/build-mark/repo-connectors - docs/verification/build-mark/repo-connectors/github - - docs/verification/build-mark/repo-connectors/azure-dev-ops + - docs/verification/build-mark/repo-connectors/azure-devops - docs/verification/build-mark/repo-connectors/mock - docs/verification/ots - docs/template @@ -18,56 +18,57 @@ resource-path: input-files: - docs/verification/title.txt - docs/verification/introduction.md - - docs/verification/build-mark/build-mark.md + - docs/verification/build-mark.md - docs/verification/build-mark/program.md - - docs/verification/build-mark/cli/cli.md + - docs/verification/build-mark/cli.md - docs/verification/build-mark/cli/context.md - - docs/verification/build-mark/build-notes/build-notes.md + - docs/verification/build-mark/build-notes.md - docs/verification/build-mark/build-notes/build-information.md - docs/verification/build-mark/build-notes/item-info.md - docs/verification/build-mark/build-notes/web-link.md - - docs/verification/build-mark/self-test/self-test.md + - docs/verification/build-mark/self-test.md - docs/verification/build-mark/self-test/validation.md - - docs/verification/build-mark/utilities/utilities.md + - docs/verification/build-mark/utilities.md - docs/verification/build-mark/utilities/path-helpers.md - docs/verification/build-mark/utilities/process-runner.md - - docs/verification/build-mark/version/version.md + - docs/verification/build-mark/version.md - docs/verification/build-mark/version/version-comparable.md - docs/verification/build-mark/version/version-semantic.md - docs/verification/build-mark/version/version-tag.md - docs/verification/build-mark/version/version-interval.md - docs/verification/build-mark/version/version-interval-set.md - docs/verification/build-mark/version/version-commit-tag.md - - docs/verification/build-mark/configuration/configuration.md + - docs/verification/build-mark/configuration.md - docs/verification/build-mark/configuration/build-mark-config.md - docs/verification/build-mark/configuration/build-mark-config-reader.md - docs/verification/build-mark/configuration/configuration-load-result.md - docs/verification/build-mark/configuration/configuration-issue.md - docs/verification/build-mark/configuration/connector-config.md - docs/verification/build-mark/configuration/git-hub-connector-config.md - - docs/verification/build-mark/configuration/azure-dev-ops-connector-config.md + - docs/verification/build-mark/configuration/azure-devops-connector-config.md - docs/verification/build-mark/configuration/report-config.md - docs/verification/build-mark/configuration/section-config.md - docs/verification/build-mark/configuration/rule-config.md - docs/verification/build-mark/configuration/rule-match-config.md - - docs/verification/build-mark/repo-connectors/repo-connectors.md + - docs/verification/build-mark/repo-connectors.md - docs/verification/build-mark/repo-connectors/i-repo-connector.md - docs/verification/build-mark/repo-connectors/repo-connector-base.md - docs/verification/build-mark/repo-connectors/repo-connector-factory.md - docs/verification/build-mark/repo-connectors/item-router.md - docs/verification/build-mark/repo-connectors/item-controls-info.md - docs/verification/build-mark/repo-connectors/item-controls-parser.md - - docs/verification/build-mark/repo-connectors/github/github.md + - docs/verification/build-mark/repo-connectors/github.md - docs/verification/build-mark/repo-connectors/github/git-hub-repo-connector.md - docs/verification/build-mark/repo-connectors/github/git-hub-graph-ql-client.md - docs/verification/build-mark/repo-connectors/github/git-hub-graph-ql-types.md - - docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops.md - - docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops-repo-connector.md - - docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops-rest-client.md - - docs/verification/build-mark/repo-connectors/azure-dev-ops/azure-dev-ops-api-types.md - - docs/verification/build-mark/repo-connectors/azure-dev-ops/work-item-mapper.md - - docs/verification/build-mark/repo-connectors/mock/mock.md + - docs/verification/build-mark/repo-connectors/azure-devops.md + - docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md + - docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md + - docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md + - docs/verification/build-mark/repo-connectors/azure-devops/work-item-mapper.md + - docs/verification/build-mark/repo-connectors/mock.md - docs/verification/build-mark/repo-connectors/mock/mock-repo-connector.md + - docs/verification/ots.md - docs/verification/ots/buildmark.md - docs/verification/ots/fileassert.md - docs/verification/ots/pandoc.md diff --git a/docs/verification/ots.md b/docs/verification/ots.md new file mode 100644 index 00000000..63d927bf --- /dev/null +++ b/docs/verification/ots.md @@ -0,0 +1,11 @@ +# OTS Verification + +This section documents the verification evidence for each Off-The-Shelf (OTS) +component used by BuildMark. OTS components are not developed in-house; their +requirements are verified through self-validation mechanisms, CI pipeline +execution, or other documented evidence rather than by unit or integration tests +written for this project. + +Each OTS item chapter below identifies the component's required functionality, +the verification evidence used to satisfy each OTS requirement, and a coverage +mapping of OTS requirements to evidence. diff --git a/docs/verification/ots/buildmark.md b/docs/verification/ots/buildmark.md index 4420770d..4cbf090e 100644 --- a/docs/verification/ots/buildmark.md +++ b/docs/verification/ots/buildmark.md @@ -1,6 +1,6 @@ -# BuildMark +## BuildMark -## Verification Approach +### Verification Approach BuildMark is an OTS tool. Verification is achieved through the tool's built-in self-validation (`--validate`) executed in the CI pipeline. The self-validation @@ -8,7 +8,7 @@ runs all internal checks and writes results to a TRX file. Successful completion of the self-validation step constitutes evidence that the tool is functioning correctly in the build environment. -## Evidence +### Evidence The CI pipeline step `Run BuildMark self-validation` executes: @@ -18,7 +18,7 @@ dotnet buildmark --validate --results artifacts/buildmark-self-validation.trx The resulting TRX file is consumed by ReqStream to satisfy the OTS requirement. -## Requirements Coverage +### Requirements Coverage - **BuildMark-OTS-BuildMark**: CI pipeline self-validation TRX evidence from `artifacts/buildmark-self-validation.trx` diff --git a/docs/verification/ots/fileassert.md b/docs/verification/ots/fileassert.md index 7dae649c..4f13bb2f 100644 --- a/docs/verification/ots/fileassert.md +++ b/docs/verification/ots/fileassert.md @@ -1,6 +1,6 @@ -# FileAssert +## FileAssert -## Verification Approach +### Verification Approach FileAssert is an OTS tool. Verification is achieved through the tool's built-in self-validation (`--validate`) executed in the CI pipeline. The self-validation @@ -13,7 +13,7 @@ generated document (Build Notes, Code Quality, Review Plan, Review Report, Desig User Guide, and Verification). Each successful assertion confirms that FileAssert is able to inspect and validate file content as required. -## Evidence +### Evidence The CI pipeline step `Run FileAssert self-validation` executes: @@ -23,7 +23,7 @@ dotnet fileassert --validate --results artifacts/fileassert-self-validation.trx The resulting TRX file is consumed by ReqStream to satisfy the OTS requirement. -## Requirements Coverage +### Requirements Coverage - **BuildMark-OTS-FileAssert**: CI pipeline self-validation TRX evidence from `artifacts/fileassert-self-validation.trx` diff --git a/docs/verification/ots/pandoc.md b/docs/verification/ots/pandoc.md index 567279be..918810af 100644 --- a/docs/verification/ots/pandoc.md +++ b/docs/verification/ots/pandoc.md @@ -1,6 +1,6 @@ -# Pandoc +## Pandoc -## Verification Approach +### Verification Approach Pandoc is an OTS document conversion tool. Verification is achieved through repeated document generation in the CI pipeline. Pandoc converts markdown source @@ -9,7 +9,7 @@ Review Report, Design, User Guide, and Verification). FileAssert then validates each generated HTML file contains expected content, providing evidence of correct Pandoc operation. -## Evidence +### Evidence The CI pipeline generates HTML output using Pandoc for each document section, and FileAssert validates the output. For example, for the Design document: @@ -23,7 +23,7 @@ FileAssert TRX files (`fileassert-build-notes.trx`, `fileassert-code-quality.trx `fileassert-code-review.trx`, `fileassert-design.trx`, `fileassert-user-guide.trx`, `fileassert-verification.trx`) are consumed by ReqStream to satisfy the OTS requirement. -## Requirements Coverage +### Requirements Coverage - **BuildMark-OTS-Pandoc**: CI pipeline document generation evidence from multiple FileAssert TRX results confirming successful HTML conversion diff --git a/docs/verification/ots/reqstream.md b/docs/verification/ots/reqstream.md index 5e958fcd..9ea38541 100644 --- a/docs/verification/ots/reqstream.md +++ b/docs/verification/ots/reqstream.md @@ -1,6 +1,6 @@ -# ReqStream +## ReqStream -## Verification Approach +### Verification Approach ReqStream is an OTS requirements traceability tool. Verification is achieved through the tool's built-in self-validation (`--validate`) executed in the CI pipeline. The @@ -13,7 +13,7 @@ requirements YAML files against TRX evidence and enforces that all requirements satisfied (`--enforce`). Successful execution of ReqStream in enforcement mode provides further evidence of correct operation. -## Evidence +### Evidence The CI pipeline step `Run ReqStream self-validation` executes: @@ -23,7 +23,7 @@ dotnet reqstream --validate --results artifacts/reqstream-self-validation.trx The resulting TRX file is consumed by ReqStream itself to satisfy the OTS requirement. -## Requirements Coverage +### Requirements Coverage - **BuildMark-OTS-ReqStream**: CI pipeline self-validation TRX evidence from `artifacts/reqstream-self-validation.trx` diff --git a/docs/verification/ots/reviewmark.md b/docs/verification/ots/reviewmark.md index d65c470d..e0565968 100644 --- a/docs/verification/ots/reviewmark.md +++ b/docs/verification/ots/reviewmark.md @@ -1,6 +1,6 @@ -# ReviewMark +## ReviewMark -## Verification Approach +### Verification Approach ReviewMark is an OTS code review enforcement tool. Verification is achieved through the tool's built-in self-validation (`--validate`) executed in the CI pipeline. The @@ -12,7 +12,7 @@ Additionally, ReviewMark is exercised operationally when it generates the Review and Review Report documents from the `.reviewmark.yaml` configuration. Successful document generation provides further evidence of correct operation. -## Evidence +### Evidence The CI pipeline step `Run ReviewMark self-validation` executes: @@ -22,7 +22,7 @@ dotnet reviewmark --validate --results artifacts/reviewmark-self-validation.trx The resulting TRX file is consumed by ReqStream to satisfy the OTS requirement. -## Requirements Coverage +### Requirements Coverage - **BuildMark-OTS-ReviewMark**: CI pipeline self-validation TRX evidence from `artifacts/reviewmark-self-validation.trx` diff --git a/docs/verification/ots/sarifmark.md b/docs/verification/ots/sarifmark.md index ef55ba5f..064b2b71 100644 --- a/docs/verification/ots/sarifmark.md +++ b/docs/verification/ots/sarifmark.md @@ -1,6 +1,6 @@ -# SarifMark +## SarifMark -## Verification Approach +### Verification Approach SarifMark is an OTS SARIF report generation tool. Verification is achieved through the tool's built-in self-validation (`--validate`) executed in the CI pipeline. The @@ -12,7 +12,7 @@ Additionally, SarifMark is exercised operationally when it processes the CodeQL output and generates the CodeQL quality report markdown. Successful report generation provides further evidence of correct operation. -## Evidence +### Evidence The CI pipeline step `Run SarifMark self-validation` executes: @@ -22,7 +22,7 @@ dotnet sarifmark --validate --results artifacts/sarifmark-self-validation.trx The resulting TRX file is consumed by ReqStream to satisfy the OTS requirement. -## Requirements Coverage +### Requirements Coverage - **BuildMark-OTS-SarifMark**: CI pipeline self-validation TRX evidence from `artifacts/sarifmark-self-validation.trx` diff --git a/docs/verification/ots/sonarmark.md b/docs/verification/ots/sonarmark.md index 3f88abba..e6f02bbe 100644 --- a/docs/verification/ots/sonarmark.md +++ b/docs/verification/ots/sonarmark.md @@ -1,6 +1,6 @@ -# SonarMark +## SonarMark -## Verification Approach +### Verification Approach SonarMark is an OTS SonarCloud quality report generation tool. Verification is achieved through the tool's built-in self-validation (`--validate`) executed in the CI pipeline. @@ -12,7 +12,7 @@ Additionally, SonarMark is exercised operationally when it queries the SonarClou and generates the SonarCloud quality report markdown. Successful report generation provides further evidence of correct operation. -## Evidence +### Evidence The CI pipeline step `Run SonarMark self-validation` executes: @@ -22,7 +22,7 @@ dotnet sonarmark --validate --results artifacts/sonarmark-self-validation.trx The resulting TRX file is consumed by ReqStream to satisfy the OTS requirement. -## Requirements Coverage +### Requirements Coverage - **BuildMark-OTS-SonarMark**: CI pipeline self-validation TRX evidence from `artifacts/sonarmark-self-validation.trx` diff --git a/docs/verification/ots/versionmark.md b/docs/verification/ots/versionmark.md index e9500be2..41de0ffa 100644 --- a/docs/verification/ots/versionmark.md +++ b/docs/verification/ots/versionmark.md @@ -1,6 +1,6 @@ -# VersionMark +## VersionMark -## Verification Approach +### Verification Approach VersionMark is an OTS tool version capture tool. Verification is achieved through the tool's built-in self-validation (`--validate`) executed in the CI pipeline across @@ -12,7 +12,7 @@ Additionally, VersionMark is exercised operationally in every job to capture and tool version information. Successful version capture and publication provides further evidence of correct operation. -## Evidence +### Evidence The CI pipeline runs VersionMark self-validation in multiple jobs: @@ -23,7 +23,7 @@ dotnet versionmark --validate --results artifacts/versionmark-self-validation.tr The resulting TRX files are consumed by ReqStream to satisfy the OTS requirement. -## Requirements Coverage +### Requirements Coverage - **BuildMark-OTS-VersionMark**: CI pipeline self-validation TRX evidence from `artifacts/versionmark-self-validation.trx` and diff --git a/docs/verification/ots/weasyprint.md b/docs/verification/ots/weasyprint.md index be4eba56..e2dd86bd 100644 --- a/docs/verification/ots/weasyprint.md +++ b/docs/verification/ots/weasyprint.md @@ -1,6 +1,6 @@ -# WeasyPrint +## WeasyPrint -## Verification Approach +### Verification Approach WeasyPrint is an OTS HTML-to-PDF rendering tool. Verification is achieved through repeated document generation in the CI pipeline. WeasyPrint converts HTML files to PDF @@ -9,7 +9,7 @@ Design, User Guide, and Verification). FileAssert then validates that each gener PDF file contains expected content and metadata, providing evidence of correct WeasyPrint operation. -## Evidence +### Evidence The CI pipeline generates PDF output using WeasyPrint for each document section, and FileAssert validates the output. For example, for the Design document: @@ -24,7 +24,7 @@ FileAssert TRX files (`fileassert-build-notes.trx`, `fileassert-code-quality.trx `fileassert-code-review.trx`, `fileassert-design.trx`, `fileassert-user-guide.trx`, `fileassert-verification.trx`) are consumed by ReqStream to satisfy the OTS requirement. -## Requirements Coverage +### Requirements Coverage - **BuildMark-OTS-WeasyPrint**: CI pipeline document generation evidence from multiple FileAssert TRX results confirming successful PDF rendering diff --git a/docs/verification/ots/xunit.md b/docs/verification/ots/xunit.md index e5e57b87..41633ec9 100644 --- a/docs/verification/ots/xunit.md +++ b/docs/verification/ots/xunit.md @@ -1,6 +1,6 @@ -# xUnit +## xUnit -## Verification Approach +### Verification Approach xUnit is an OTS unit testing framework. Verification is achieved through the framework's execution of all project unit tests in the CI pipeline. xUnit discovers and runs all test @@ -8,7 +8,7 @@ methods in `DemaConsulting.BuildMark.Tests`, writes TRX result files, and report outcomes. Successful test execution across all supported operating systems and .NET runtime versions constitutes evidence that xUnit is functioning correctly. -## Evidence +### Evidence The CI pipeline step `Test` executes: @@ -23,7 +23,7 @@ The resulting TRX files are consumed by ReqStream to satisfy unit test requireme The matrix of operating systems (Windows, Ubuntu, macOS) and .NET versions (8, 9, 10) provides broad platform coverage evidence. -## Requirements Coverage +### Requirements Coverage - **BuildMark-OTS-xUnit**: CI pipeline test execution TRX evidence confirming that xUnit discovers and runs tests on all supported platforms diff --git a/requirements.yaml b/requirements.yaml index 80b1c9e9..4c62363d 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -1,35 +1,35 @@ --- includes: - - docs/reqstream/build-mark/build-mark.yaml + - docs/reqstream/build-mark.yaml - docs/reqstream/build-mark/platform-requirements.yaml - docs/reqstream/build-mark/program.yaml - - docs/reqstream/build-mark/cli/cli.yaml + - docs/reqstream/build-mark/cli.yaml - docs/reqstream/build-mark/cli/context.yaml - - docs/reqstream/build-mark/build-notes/build-notes.yaml + - docs/reqstream/build-mark/build-notes.yaml - docs/reqstream/build-mark/build-notes/build-information.yaml - docs/reqstream/build-mark/build-notes/item-info.yaml - docs/reqstream/build-mark/build-notes/web-link.yaml - - docs/reqstream/build-mark/self-test/self-test.yaml + - docs/reqstream/build-mark/self-test.yaml - docs/reqstream/build-mark/self-test/validation.yaml - - docs/reqstream/build-mark/utilities/utilities.yaml + - docs/reqstream/build-mark/utilities.yaml - docs/reqstream/build-mark/utilities/path-helpers.yaml - docs/reqstream/build-mark/utilities/process-runner.yaml - - docs/reqstream/build-mark/version/version.yaml - - docs/reqstream/build-mark/repo-connectors/repo-connectors.yaml + - docs/reqstream/build-mark/version.yaml + - docs/reqstream/build-mark/repo-connectors.yaml - docs/reqstream/build-mark/repo-connectors/repo-connector-base.yaml - docs/reqstream/build-mark/repo-connectors/item-router.yaml - docs/reqstream/build-mark/repo-connectors/item-controls-parser.yaml - docs/reqstream/build-mark/repo-connectors/repo-connector-factory.yaml + - docs/reqstream/build-mark/repo-connectors/github.yaml - docs/reqstream/build-mark/repo-connectors/github/github-repo-connector.yaml - - docs/reqstream/build-mark/repo-connectors/github/github.yaml - docs/reqstream/build-mark/repo-connectors/github/github-graphql-client.yaml + - docs/reqstream/build-mark/repo-connectors/azure-devops.yaml - docs/reqstream/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.yaml - - docs/reqstream/build-mark/repo-connectors/azure-devops/azure-devops.yaml - docs/reqstream/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.yaml - docs/reqstream/build-mark/repo-connectors/azure-devops/work-item-mapper.yaml + - docs/reqstream/build-mark/repo-connectors/mock.yaml - docs/reqstream/build-mark/repo-connectors/mock/mock-repo-connector.yaml - - docs/reqstream/build-mark/repo-connectors/mock/mock.yaml - - docs/reqstream/build-mark/configuration/configuration.yaml + - docs/reqstream/build-mark/configuration.yaml - docs/reqstream/ots/xunit.yaml - docs/reqstream/ots/reqstream.yaml - docs/reqstream/ots/buildmark.yaml