diff --git a/.cspell.yaml b/.cspell.yaml index 87c7064..7d3bd6b 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -18,7 +18,7 @@ words: - Blockquotes - buildmark - BuildMark - - buildnotes + - build_notes - camelcase - Checkmarx - CodeQL @@ -59,8 +59,12 @@ words: - ReqStream - reviewmark - ReviewMark - - reviewplan - - reviewreport + - code_quality + - code_review_plan + - code_review_report + - requirements_doc + - requirements_report + - trace_matrix - Sarif - SarifMark - SBOM @@ -76,7 +80,6 @@ words: - templatetool - testname - TMPL - - tracematrix - triaging - Trivy - trx diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 3292fce..321ca4c 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -43,9 +43,7 @@ Before submitting this pull request, ensure you have completed the following: Please run the following checks before submitting: -- [ ] **Spell checker passes**: `cspell "**/*.{md,cs}"` -- [ ] **Markdown linter passes**: `markdownlint "**/*.md"` -- [ ] **YAML linter passes**: `yamllint .` +- [ ] **All linters pass**: `./lint.sh` (Unix/macOS) or `cmd /c lint.bat` / `./lint.bat` (Windows) ### Testing diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 47e2d63..8ae8ff1 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -35,7 +35,7 @@ jobs: dotnet tool restore - name: Setup Node.js - uses: actions/setup-node@v4 + uses: actions/setup-node@v6 with: node-version: 24.x @@ -494,16 +494,16 @@ jobs: dotnet reqstream --requirements requirements.yaml --tests "artifacts/**/*.trx" - --report docs/requirements/requirements.md - --justifications docs/justifications/justifications.md - --matrix docs/tracematrix/tracematrix.md + --report docs/requirements_doc/requirements.md + --justifications docs/requirements_doc/justifications.md + --matrix docs/requirements_report/trace_matrix.md --enforce - name: Generate CodeQL Quality Report with SarifMark run: > dotnet sarifmark --sarif artifacts/csharp.sarif - --report docs/quality/codeql-quality.md + --report docs/code_quality/codeql-quality.md --heading "Template DotNet Tool CodeQL Analysis" --report-depth 1 @@ -511,7 +511,7 @@ jobs: shell: bash run: | echo "=== CodeQL Quality Report ===" - cat docs/quality/codeql-quality.md + cat docs/code_quality/codeql-quality.md - name: Generate SonarCloud Quality Report shell: bash @@ -523,36 +523,37 @@ jobs: --project-key demaconsulting_TemplateDotNetTool --branch ${{ github.ref_name }} --token "$SONAR_TOKEN" - --report docs/quality/sonar-quality.md + --report docs/code_quality/sonar-quality.md --report-depth 1 - name: Display SonarCloud Quality Report shell: bash run: | echo "=== SonarCloud Quality Report ===" - cat docs/quality/sonar-quality.md + cat docs/code_quality/sonar-quality.md - name: Generate Review Plan and Review Report with ReviewMark shell: bash + # TODO: Add --enforce once reviews branch is populated with review evidence PDFs and index.json run: > dotnet reviewmark --definition .reviewmark.yaml - --plan docs/reviewplan/review-plan.md + --plan docs/code_review_plan/plan.md --plan-depth 1 - --report docs/reviewreport/review-report.md + --report docs/code_review_report/report.md --report-depth 1 - name: Display Review Plan shell: bash run: | echo "=== Review Plan ===" - cat docs/reviewplan/review-plan.md + cat docs/code_review_plan/plan.md - name: Display Review Report shell: bash run: | echo "=== Review Report ===" - cat docs/reviewreport/review-report.md + cat docs/code_review_report/report.md - name: Generate Build Notes with BuildMark shell: bash @@ -561,20 +562,20 @@ jobs: run: > dotnet buildmark --build-version ${{ inputs.version }} - --report docs/buildnotes.md + --report docs/build_notes.md --report-depth 1 - name: Display Build Notes Report shell: bash run: | echo "=== Build Notes Report ===" - cat docs/buildnotes.md + cat docs/build_notes.md - name: Publish Tool Versions shell: bash run: | echo "Publishing tool versions..." - dotnet versionmark --publish --report docs/buildnotes/versions.md --report-depth 1 \ + dotnet versionmark --publish --report docs/build_notes/versions.md --report-depth 1 \ -- "artifacts/**/versionmark-*.json" echo "✓ Tool versions published" @@ -582,7 +583,7 @@ jobs: shell: bash run: | echo "=== Tool Versions Report ===" - cat docs/buildnotes/versions.md + cat docs/build_notes/versions.md # === GENERATE HTML DOCUMENTS WITH PANDOC === # This section converts markdown documents to HTML using Pandoc. @@ -592,11 +593,11 @@ jobs: shell: bash run: > dotnet pandoc - --defaults docs/buildnotes/definition.yaml + --defaults docs/build_notes/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/buildnotes/buildnotes.html + --output docs/build_notes/buildnotes.html - name: Generate Guide HTML with Pandoc shell: bash @@ -612,61 +613,51 @@ jobs: shell: bash run: > dotnet pandoc - --defaults docs/quality/definition.yaml + --defaults docs/code_quality/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/quality/quality.html + --output docs/code_quality/quality.html - name: Generate Requirements HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/requirements/definition.yaml - --filter node_modules/.bin/mermaid-filter.cmd - --metadata version="${{ inputs.version }}" - --metadata date="$(date +'%Y-%m-%d')" - --output docs/requirements/requirements.html - - - name: Generate Requirements Justifications HTML with Pandoc - shell: bash - run: > - dotnet pandoc - --defaults docs/justifications/definition.yaml + --defaults docs/requirements_doc/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/justifications/justifications.html + --output docs/requirements_doc/requirements.html - name: Generate Trace Matrix HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/tracematrix/definition.yaml + --defaults docs/requirements_report/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/tracematrix/tracematrix.html + --output docs/requirements_report/trace_matrix.html - name: Generate Review Plan HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/reviewplan/definition.yaml + --defaults docs/code_review_plan/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/reviewplan/review-plan.html + --output docs/code_review_plan/plan.html - name: Generate Review Report HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/reviewreport/definition.yaml + --defaults docs/code_review_report/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/reviewreport/review-report.html + --output docs/code_review_report/report.html # === GENERATE PDF DOCUMENTS WITH WEASYPRINT === # This section converts HTML documents to PDF using Weasyprint. @@ -676,7 +667,7 @@ jobs: run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/buildnotes/buildnotes.html + docs/build_notes/buildnotes.html "docs/TemplateDotNetTool Build Notes.pdf" - name: Generate Guide PDF with Weasyprint @@ -690,42 +681,35 @@ jobs: run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/quality/quality.html + docs/code_quality/quality.html "docs/TemplateDotNetTool Code Quality.pdf" - name: Generate Requirements PDF with Weasyprint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/requirements/requirements.html + docs/requirements_doc/requirements.html "docs/TemplateDotNetTool Requirements.pdf" - - name: Generate Requirements Justifications PDF with Weasyprint - run: > - dotnet weasyprint - --pdf-variant pdf/a-3u - docs/justifications/justifications.html - "docs/TemplateDotNetTool Requirements Justifications.pdf" - - name: Generate Trace Matrix PDF with Weasyprint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/tracematrix/tracematrix.html + docs/requirements_report/trace_matrix.html "docs/TemplateDotNetTool Trace Matrix.pdf" - name: Generate Review Plan PDF with Weasyprint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/reviewplan/review-plan.html + docs/code_review_plan/plan.html "docs/TemplateDotNetTool Review Plan.pdf" - name: Generate Review Report PDF with Weasyprint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/reviewreport/review-report.html + docs/code_review_report/report.html "docs/TemplateDotNetTool Review Report.pdf" # === UPLOAD ARTIFACTS === @@ -738,4 +722,4 @@ jobs: name: documents path: | docs/*.pdf - docs/buildnotes.md + docs/build_notes.md diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 9a81642..b019d74 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -63,10 +63,10 @@ jobs: name: documents path: artifacts - - name: Move buildnotes.md to root + - name: Move build_notes.md to root run: | set -e - mv artifacts/buildnotes.md buildnotes.md + mv artifacts/build_notes.md buildnotes.md - name: Create GitHub Release if: inputs.publish == 'release' || inputs.publish == 'publish' diff --git a/.gitignore b/.gitignore index fb7e339..48dc886 100644 --- a/.gitignore +++ b/.gitignore @@ -91,15 +91,15 @@ __pycache__/ docs/**/*.html docs/**/*.pdf !docs/template/** -docs/requirements/requirements.md -docs/justifications/justifications.md -docs/tracematrix/tracematrix.md -docs/quality/codeql-quality.md -docs/quality/sonar-quality.md -docs/reviewplan/review-plan.md -docs/reviewreport/review-report.md -docs/buildnotes.md -docs/buildnotes/versions.md +docs/requirements_doc/requirements.md +docs/requirements_doc/justifications.md +docs/requirements_report/trace_matrix.md +docs/code_quality/codeql-quality.md +docs/code_quality/sonar-quality.md +docs/code_review_plan/plan.md +docs/code_review_report/report.md +docs/build_notes.md +docs/build_notes/versions.md # Test results TestResults/ diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 84dc809..093a00e 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -1,13 +1,15 @@ --- # ReviewMark Configuration File # This file defines which files require review, where the evidence store is located, -# and how files are grouped into named review-sets. +# and how files are grouped into named review-sets following software unit boundaries. # Patterns identifying all files that require review. # Processed in order; prefix a pattern with '!' to exclude. needs-review: - - "**/*.cs" - - "!**/obj/**" + - "**/*.cs" # All C# source and test files + - "docs/reqstream/**/*.yaml" # Requirements files + - "!**/obj/**" # Exclude build output + - "!**/bin/**" # Exclude build output # Evidence source: review data and index.json are located in the 'reviews' branch # of this repository, accessed through the GitHub public HTTPS raw content access. @@ -18,26 +20,54 @@ evidence-source: location: https://raw.githubusercontent.com/demaconsulting/TemplateDotNetTool/reviews/index.json # Review sets grouping files by logical unit of review. +# Each review-set groups requirements, source, and tests for a coherent software unit +# so that an AI-assisted review can verify consistency across the full evidence chain. reviews: - - id: TemplateTool-CLI-Review - title: Review of Template DotNet Tool CLI + # Software unit reviews - one per class + - id: TemplateTool-Context + title: Review of Template DotNet Tool Context Unit paths: - - "src/**/Program.cs" + - "docs/reqstream/unit-context.yaml" - "src/**/Context.cs" - - "test/**/ProgramTests.cs" - "test/**/ContextTests.cs" - - id: TemplateTool-Utilities-Review - title: Review of Template DotNet Tool Utilities + - id: TemplateTool-Program + title: Review of Template DotNet Tool Program Unit paths: - - "src/**/PathHelpers.cs" + - "docs/reqstream/unit-program.yaml" + - "src/**/Program.cs" + - "test/**/ProgramTests.cs" + - "test/**/IntegrationTests.cs" + - "test/**/Runner.cs" + - "test/**/AssemblyInfo.cs" + + - id: TemplateTool-Validation + title: Review of Template DotNet Tool Validation Unit + paths: + - "docs/reqstream/unit-validation.yaml" - "src/**/Validation.cs" - - "test/**/PathHelpersTests.cs" - "test/**/ValidationTests.cs" - - id: TemplateTool-Tests-Review - title: Review of Template DotNet Tool Integration Tests + - id: TemplateTool-PathHelpers + title: Review of Template DotNet Tool PathHelpers Unit paths: - - "test/**/IntegrationTests.cs" - - "test/**/Runner.cs" - - "test/**/AssemblyInfo.cs" + - "docs/reqstream/unit-path-helpers.yaml" + - "src/**/PathHelpers.cs" + - "test/**/PathHelpersTests.cs" + + # Platform and OTS dependency reviews + - id: Platform-Support + title: Review of Platform and Runtime Support Requirements + paths: + - "docs/reqstream/platform-requirements.yaml" + + - id: OTS-Dependencies + title: Review of Off-The-Shelf Software Dependencies + paths: + - "docs/reqstream/ots-mstest.yaml" + - "docs/reqstream/ots-reqstream.yaml" + - "docs/reqstream/ots-buildmark.yaml" + - "docs/reqstream/ots-versionmark.yaml" + - "docs/reqstream/ots-sarifmark.yaml" + - "docs/reqstream/ots-sonarmark.yaml" + - "docs/reqstream/ots-reviewmark.yaml" diff --git a/AGENTS.md b/AGENTS.md index 633eba7..41f3cfd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,7 +44,8 @@ implementation demonstrating best practices for DEMA Consulting .NET CLI tools. ## Key Files -- **`requirements.yaml`** - All requirements with test linkage (enforced via `dotnet reqstream --enforce`) +- **`requirements.yaml`** - Root requirements file using `includes:` to reference `docs/reqstream/` files +- **`docs/reqstream/`** - Per-software-unit, platform, and OTS requirements YAML files - **`.editorconfig`** - Code style (file-scoped namespaces, 4-space indent, UTF-8, LF endings) - **`.cspell.yaml`, `.markdownlint-cli2.yaml`, `.yamllint.yaml`** - Linting configs @@ -99,6 +100,16 @@ ensures the CI evidence comes specifically from the required environment. ## Project Structure +- `docs/` - Documentation and compliance artifacts + - `reqstream/` - Per-software-unit, platform, and OTS requirements YAML files (included by root `requirements.yaml`) + - Auto-generated reports (requirements, justifications, trace matrix) +- `src/` - Source code files +- `test/` - Test files +- `.github/workflows/` - CI/CD pipeline definitions (`build.yaml`, `build_on_push.yaml`, `release.yaml`) +- Configuration files: `.editorconfig`, `.reviewmark.yaml`, `.cspell.yaml`, `.yamllint.yaml`, etc. + +### Key Source Files + - **Context.cs**: Handles command-line argument parsing, logging, and output - **Program.cs**: Main entry point with version/help/validation routing - **Validation.cs**: Self-validation tests with TRX/JUnit output support @@ -124,7 +135,7 @@ build.bat # Windows ## Documentation - **User Guide**: `docs/guide/guide.md` -- **Requirements**: `requirements.yaml` -> auto-generated docs +- **Requirements**: `requirements.yaml` includes `docs/reqstream/` files → auto-generated docs - **Build Notes**: Auto-generated via BuildMark - **Code Quality**: Auto-generated via CodeQL and SonarMark - **Trace Matrix**: Auto-generated via ReqStream diff --git a/docs/build_notes/definition.yaml b/docs/build_notes/definition.yaml new file mode 100644 index 0000000..207a375 --- /dev/null +++ b/docs/build_notes/definition.yaml @@ -0,0 +1,12 @@ +--- +resource-path: + - docs/build_notes + - docs/template +input-files: + - docs/build_notes/title.txt + - docs/build_notes/introduction.md + - docs/build_notes.md + - docs/build_notes/versions.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/buildnotes/introduction.md b/docs/build_notes/introduction.md similarity index 100% rename from docs/buildnotes/introduction.md rename to docs/build_notes/introduction.md diff --git a/docs/buildnotes/title.txt b/docs/build_notes/title.txt similarity index 100% rename from docs/buildnotes/title.txt rename to docs/build_notes/title.txt diff --git a/docs/buildnotes/definition.yaml b/docs/buildnotes/definition.yaml deleted file mode 100644 index 62699f2..0000000 --- a/docs/buildnotes/definition.yaml +++ /dev/null @@ -1,12 +0,0 @@ ---- -resource-path: - - docs/buildnotes - - docs/template -input-files: - - docs/buildnotes/title.txt - - docs/buildnotes/introduction.md - - docs/buildnotes.md - - docs/buildnotes/versions.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/code_quality/definition.yaml b/docs/code_quality/definition.yaml new file mode 100644 index 0000000..68c58f2 --- /dev/null +++ b/docs/code_quality/definition.yaml @@ -0,0 +1,12 @@ +--- +resource-path: + - docs/code_quality + - docs/template +input-files: + - docs/code_quality/title.txt + - docs/code_quality/introduction.md + - docs/code_quality/codeql-quality.md + - docs/code_quality/sonar-quality.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/quality/introduction.md b/docs/code_quality/introduction.md similarity index 100% rename from docs/quality/introduction.md rename to docs/code_quality/introduction.md diff --git a/docs/quality/title.txt b/docs/code_quality/title.txt similarity index 100% rename from docs/quality/title.txt rename to docs/code_quality/title.txt diff --git a/docs/code_review_plan/definition.yaml b/docs/code_review_plan/definition.yaml new file mode 100644 index 0000000..3a24f0b --- /dev/null +++ b/docs/code_review_plan/definition.yaml @@ -0,0 +1,11 @@ +--- +resource-path: + - docs/code_review_plan + - docs/template +input-files: + - docs/code_review_plan/title.txt + - docs/code_review_plan/introduction.md + - docs/code_review_plan/plan.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/reviewplan/introduction.md b/docs/code_review_plan/introduction.md similarity index 89% rename from docs/reviewplan/introduction.md rename to docs/code_review_plan/introduction.md index da84912..15de1d9 100644 --- a/docs/reviewplan/introduction.md +++ b/docs/code_review_plan/introduction.md @@ -14,7 +14,8 @@ one named review-set. This review plan covers: - C# source code files requiring formal review -- Mapping of C# source files to named review-sets +- YAML configuration and requirements files requiring formal review +- Mapping of reviewed files to named review-sets ## Generation Source diff --git a/docs/reviewplan/title.txt b/docs/code_review_plan/title.txt similarity index 100% rename from docs/reviewplan/title.txt rename to docs/code_review_plan/title.txt diff --git a/docs/code_review_report/definition.yaml b/docs/code_review_report/definition.yaml new file mode 100644 index 0000000..6498e6c --- /dev/null +++ b/docs/code_review_report/definition.yaml @@ -0,0 +1,11 @@ +--- +resource-path: + - docs/code_review_report + - docs/template +input-files: + - docs/code_review_report/title.txt + - docs/code_review_report/introduction.md + - docs/code_review_report/report.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/reviewreport/introduction.md b/docs/code_review_report/introduction.md similarity index 100% rename from docs/reviewreport/introduction.md rename to docs/code_review_report/introduction.md diff --git a/docs/reviewreport/title.txt b/docs/code_review_report/title.txt similarity index 100% rename from docs/reviewreport/title.txt rename to docs/code_review_report/title.txt diff --git a/docs/guide/guide.md b/docs/guide/guide.md index 4abb284..bc22419 100644 --- a/docs/guide/guide.md +++ b/docs/guide/guide.md @@ -16,7 +16,8 @@ This user guide covers: # Continuous Compliance -This template follows the [Continuous Compliance][continuous-compliance] methodology, which ensures +This template follows the +[Continuous Compliance](https://github.com/demaconsulting/ContinuousCompliance) methodology, which ensures compliance evidence is generated automatically on every CI run. ## Key Practices @@ -157,6 +158,3 @@ templatetool --validate --results validation-results.trx ```bash templatetool --silent --log tool-output.log ``` - - -[continuous-compliance]: https://github.com/demaconsulting/ContinuousCompliance diff --git a/docs/justifications/definition.yaml b/docs/justifications/definition.yaml deleted file mode 100644 index d0bbbee..0000000 --- a/docs/justifications/definition.yaml +++ /dev/null @@ -1,11 +0,0 @@ ---- -resource-path: - - docs/justifications - - docs/template -input-files: - - docs/justifications/title.txt - - docs/justifications/introduction.md - - docs/justifications/justifications.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/justifications/introduction.md b/docs/justifications/introduction.md deleted file mode 100644 index a6fa556..0000000 --- a/docs/justifications/introduction.md +++ /dev/null @@ -1,29 +0,0 @@ -# Introduction - -This document contains the justifications for the requirements of the Template DotNet Tool project. - -## Purpose - -This justifications document provides the rationale behind each requirement in the Template DotNet Tool -project. Each requirement justification explains why the requirement exists, what problem it -solves, and how it contributes to the overall value of the tool. - -## Scope - -This document covers justifications for: - -- Command-line interface requirements -- Self-validation framework requirements -- Test result output requirements -- Logging requirements -- Platform support requirements -- Documentation generation requirements - -## Audience - -This document is intended for: - -- Software developers understanding design decisions -- Quality assurance teams reviewing requirement rationale -- Project stakeholders evaluating project scope -- Compliance and audit teams reviewing requirements traceability diff --git a/docs/justifications/title.txt b/docs/justifications/title.txt deleted file mode 100644 index 0497fd5..0000000 --- a/docs/justifications/title.txt +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Template DotNet Tool Requirements Justifications -subtitle: Requirements Justifications for the Template DotNet Tool -author: DEMA Consulting -description: Requirements Justifications for the Template DotNet Tool -lang: en-US -keywords: - - Template DotNet Tool - - Requirements - - Justifications - - .NET - - Documentation ---- diff --git a/docs/quality/definition.yaml b/docs/quality/definition.yaml deleted file mode 100644 index 1b63510..0000000 --- a/docs/quality/definition.yaml +++ /dev/null @@ -1,12 +0,0 @@ ---- -resource-path: - - docs/quality - - docs/template -input-files: - - docs/quality/title.txt - - docs/quality/introduction.md - - docs/quality/codeql-quality.md - - docs/quality/sonar-quality.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/reqstream/ots-buildmark.yaml b/docs/reqstream/ots-buildmark.yaml new file mode 100644 index 0000000..bd2a0ab --- /dev/null +++ b/docs/reqstream/ots-buildmark.yaml @@ -0,0 +1,20 @@ +--- +# BuildMark OTS Software Requirements +# +# Requirements for the BuildMark build documentation tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: BuildMark Requirements + requirements: + - id: Template-OTS-BuildMark + title: BuildMark shall generate build-notes documentation from GitHub Actions metadata. + justification: | + DemaConsulting.BuildMark queries the GitHub API to capture workflow run details and + renders them as a markdown build-notes document included in the release artifacts. + It runs as part of the same CI pipeline that produces the TRX test results, so a + successful pipeline run is evidence that BuildMark executed without error. + tags: [ots] + tests: + - BuildMark_MarkdownReportGeneration diff --git a/docs/reqstream/ots-mstest.yaml b/docs/reqstream/ots-mstest.yaml new file mode 100644 index 0000000..bc37ed0 --- /dev/null +++ b/docs/reqstream/ots-mstest.yaml @@ -0,0 +1,27 @@ +--- +# MSTest OTS Software Requirements +# +# Requirements for the MSTest testing framework functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: MSTest Requirements + requirements: + - id: Template-OTS-MSTest + title: MSTest shall execute unit tests and report results. + justification: | + MSTest (MSTest.TestFramework and MSTest.TestAdapter) is the unit-testing framework used + by the project. It discovers and runs all test methods and writes TRX result files that + feed into coverage reporting and requirements traceability. Passing tests confirm the + framework is functioning correctly. + tags: [ots] + tests: + - Context_Create_NoArguments_ReturnsDefaultContext + - Context_Create_VersionFlag_SetsVersionTrue + - Context_Create_SilentFlag_SetsSilentTrue + - Context_Create_LogFlag_OpensLogFile + - Context_Create_UnknownArgument_ThrowsArgumentException + - PathHelpers_SafePathCombine_ValidPaths_CombinesCorrectly + - Program_Run_WithVersionFlag_DisplaysVersionOnly + - Validation_Run_WithSilentContext_PrintsSummary diff --git a/docs/reqstream/ots-reqstream.yaml b/docs/reqstream/ots-reqstream.yaml new file mode 100644 index 0000000..5f49d09 --- /dev/null +++ b/docs/reqstream/ots-reqstream.yaml @@ -0,0 +1,21 @@ +--- +# ReqStream OTS Software Requirements +# +# Requirements for the ReqStream requirements traceability tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: ReqStream Requirements + requirements: + - id: Template-OTS-ReqStream + title: ReqStream shall enforce that every requirement is linked to passing test evidence. + justification: | + DemaConsulting.ReqStream processes requirements.yaml and the TRX test-result files to + produce a requirements report, justifications document, and traceability matrix. When + run with --enforce, it exits with a non-zero code if any requirement lacks test evidence, + making unproven requirements a build-breaking condition. A successful pipeline run with + --enforce proves all requirements are covered and that ReqStream is functioning. + tags: [ots] + tests: + - ReqStream_EnforcementMode diff --git a/docs/reqstream/ots-reviewmark.yaml b/docs/reqstream/ots-reviewmark.yaml new file mode 100644 index 0000000..975b31f --- /dev/null +++ b/docs/reqstream/ots-reviewmark.yaml @@ -0,0 +1,21 @@ +--- +# ReviewMark OTS Software Requirements +# +# Requirements for the ReviewMark file review tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: ReviewMark Requirements + requirements: + - id: Template-OTS-ReviewMark + title: ReviewMark shall generate a review plan and review report from the review configuration. + justification: | + DemaConsulting.ReviewMark reads the .reviewmark.yaml configuration and the review + evidence store to produce a review plan and review report documenting file review + coverage and currency. It runs in the same CI pipeline that produces the TRX test + results, so a successful pipeline run is evidence that ReviewMark executed without error. + tags: [ots] + tests: + - ReviewMark_ReviewPlanGeneration + - ReviewMark_ReviewReportGeneration diff --git a/docs/reqstream/ots-sarifmark.yaml b/docs/reqstream/ots-sarifmark.yaml new file mode 100644 index 0000000..fbc97ec --- /dev/null +++ b/docs/reqstream/ots-sarifmark.yaml @@ -0,0 +1,21 @@ +--- +# SarifMark OTS Software Requirements +# +# Requirements for the SarifMark SARIF report processing tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: SarifMark Requirements + requirements: + - id: Template-OTS-SarifMark + title: SarifMark shall convert CodeQL SARIF results into a markdown report. + justification: | + DemaConsulting.SarifMark reads the SARIF output produced by CodeQL code scanning and + renders it as a human-readable markdown document included in the release artifacts. + It runs in the same CI pipeline that produces the TRX test results, so a successful + pipeline run is evidence that SarifMark executed without error. + tags: [ots] + tests: + - SarifMark_SarifReading + - SarifMark_MarkdownReportGeneration diff --git a/docs/reqstream/ots-sonarmark.yaml b/docs/reqstream/ots-sonarmark.yaml new file mode 100644 index 0000000..e9910d8 --- /dev/null +++ b/docs/reqstream/ots-sonarmark.yaml @@ -0,0 +1,23 @@ +--- +# SonarMark OTS Software Requirements +# +# Requirements for the SonarMark quality reporting tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: SonarMark Requirements + requirements: + - id: Template-OTS-SonarMark + title: SonarMark shall generate a SonarCloud quality report. + justification: | + DemaConsulting.SonarMark retrieves quality-gate and metrics data from SonarCloud and + renders it as a markdown document included in the release artifacts. It runs in the + same CI pipeline that produces the TRX test results, so a successful pipeline run is + evidence that SonarMark executed without error. + tags: [ots] + tests: + - SonarMark_QualityGateRetrieval + - SonarMark_IssuesRetrieval + - SonarMark_HotSpotsRetrieval + - SonarMark_MarkdownReportGeneration diff --git a/docs/reqstream/ots-versionmark.yaml b/docs/reqstream/ots-versionmark.yaml new file mode 100644 index 0000000..f18330e --- /dev/null +++ b/docs/reqstream/ots-versionmark.yaml @@ -0,0 +1,21 @@ +--- +# VersionMark OTS Software Requirements +# +# Requirements for the VersionMark version tracking tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: VersionMark Requirements + requirements: + - id: Template-OTS-VersionMark + title: VersionMark shall publish captured tool-version information. + justification: | + DemaConsulting.VersionMark reads version metadata for each dotnet tool used in the + pipeline and writes a versions markdown document included in the release artifacts. + It runs in the same CI pipeline that produces the TRX test results, so a successful + pipeline run is evidence that VersionMark executed without error. + tags: [ots] + tests: + - VersionMark_CapturesVersions + - VersionMark_GeneratesMarkdownReport diff --git a/docs/reqstream/platform-requirements.yaml b/docs/reqstream/platform-requirements.yaml new file mode 100644 index 0000000..728955e --- /dev/null +++ b/docs/reqstream/platform-requirements.yaml @@ -0,0 +1,71 @@ +--- +# System-Level Platform Requirements +# +# These requirements specify the platforms and runtimes the tool must support. +# They ensure the tool works across the required execution environments. +# +# Test links can include a source filter prefix (e.g. "windows@", "ubuntu@", "dotnet8.x@") to restrict +# which test results count as evidence for a requirement. This is critical for platform and runtime +# requirements - removing these filters invalidates the evidence-based proof. +# +# Source filter prefixes: +# windows@TestName - proves the test passed on a Windows platform +# ubuntu@TestName - proves the test passed on a Linux (Ubuntu) platform +# macos@TestName - proves the test passed on a macOS platform +# dotnet8.x@TestName - proves the self-validation test ran with .NET 8.x runtime +# dotnet9.x@TestName - proves the self-validation test ran with .NET 9.x runtime +# dotnet10.x@TestName - proves the self-validation test ran with .NET 10.x runtime + +sections: + - title: Platform Support + requirements: + - id: Template-Platform-Windows + title: The tool shall build and run on Windows platforms. + justification: | + DEMA Consulting tools must support Windows as a major development platform. + tests: + # Tests link to "windows" to ensure results come from Windows platform + - "windows@TemplateTool_VersionDisplay" + - "windows@TemplateTool_HelpDisplay" + + - id: Template-Platform-Linux + title: The tool shall build and run on Linux platforms. + justification: | + DEMA Consulting tools must support Linux for CI/CD and containerized environments. + tests: + # Tests link to "ubuntu" to ensure results come from Linux platform + - "ubuntu@TemplateTool_VersionDisplay" + - "ubuntu@TemplateTool_HelpDisplay" + + - id: Template-Platform-MacOS + title: The tool shall build and run on macOS platforms. + justification: | + DEMA Consulting tools must support macOS for developers using Apple platforms. + tests: + # Tests link to "macos" to ensure results come from macOS platform + - "macos@TemplateTool_VersionDisplay" + - "macos@TemplateTool_HelpDisplay" + + - id: Template-Platform-Net8 + title: The tool shall support .NET 8 runtime. + justification: | + .NET 8 is an LTS release providing long-term stability for enterprise users. + tests: + - "dotnet8.x@TemplateTool_VersionDisplay" + - "dotnet8.x@TemplateTool_HelpDisplay" + + - id: Template-Platform-Net9 + title: The tool shall support .NET 9 runtime. + justification: | + .NET 9 support enables users to leverage the latest .NET features. + tests: + - "dotnet9.x@TemplateTool_VersionDisplay" + - "dotnet9.x@TemplateTool_HelpDisplay" + + - id: Template-Platform-Net10 + title: The tool shall support .NET 10 runtime. + justification: | + .NET 10 support ensures the tool remains compatible with the latest .NET ecosystem. + tests: + - "dotnet10.x@TemplateTool_VersionDisplay" + - "dotnet10.x@TemplateTool_HelpDisplay" diff --git a/docs/reqstream/unit-context.yaml b/docs/reqstream/unit-context.yaml new file mode 100644 index 0000000..e74d577 --- /dev/null +++ b/docs/reqstream/unit-context.yaml @@ -0,0 +1,73 @@ +--- +# Software Unit Requirements for the Context Class +# +# The Context class handles command-line argument parsing and program output. +# It is the primary interface between the user's command-line invocation and +# the tool's internal logic. + +sections: + - title: Context Unit Requirements + requirements: + - id: Template-Context-ArgumentParsing + title: The Context class shall parse command-line arguments into structured properties. + justification: | + Provides a standardized approach to command-line argument parsing and output + handling across all DEMA Consulting DotNet Tools. + tests: + - Context_Create_NoArguments_ReturnsDefaultContext + - Context_Create_VersionFlag_SetsVersionTrue + - Context_Create_ShortVersionFlag_SetsVersionTrue + - Context_Create_HelpFlag_SetsHelpTrue + - Context_Create_ShortHelpFlag_H_SetsHelpTrue + - Context_Create_ShortHelpFlag_Question_SetsHelpTrue + - Context_Create_SilentFlag_SetsSilentTrue + - Context_Create_ValidateFlag_SetsValidateTrue + - Context_Create_ResultsFlag_SetsResultsFile + - Context_Create_LogFlag_OpensLogFile + + - id: Template-Context-InvalidArgs + title: The Context class shall reject unknown or malformed command-line arguments with a descriptive error. + justification: | + Providing clear feedback for invalid arguments helps users quickly correct + mistakes and prevents silent misconfiguration. + tests: + - Context_Create_UnknownArgument_ThrowsArgumentException + - Context_Create_LogFlag_WithoutValue_ThrowsArgumentException + - Context_Create_ResultsFlag_WithoutValue_ThrowsArgumentException + + - id: Template-Context-Output + title: The Context class shall write output to the console and optionally to a log file. + justification: | + Provides persistent logging for debugging and audit trails, while also + allowing console output to be suppressed in automated environments. + tests: + - Context_WriteLine_NotSilent_WritesToConsole + - Context_WriteLine_Silent_DoesNotWriteToConsole + - Context_WriteError_WritesToLogFile + + - id: Template-Context-Silent + title: The Context class shall suppress console output when the silent flag is set. + justification: | + Enables automated scripts and CI/CD pipelines to run the tool without + cluttering output logs. + tests: + - Context_Create_SilentFlag_SetsSilentTrue + - Context_WriteLine_Silent_DoesNotWriteToConsole + - Context_WriteError_Silent_DoesNotWriteToConsole + + - id: Template-Context-ErrorOutput + title: The Context class shall write error messages to stderr. + justification: | + Error messages must be written to stderr so they remain visible to the user + without polluting stdout, which consumers may pipe or redirect for data capture. + tests: + - Context_WriteError_NotSilent_WritesToConsole + - Context_WriteError_SetsErrorExitCode + + - id: Template-Context-ExitCode + title: The Context class shall track errors and expose a non-zero exit code when errors have occurred. + justification: | + Callers (scripts, CI/CD pipelines) must be able to detect failure conditions + programmatically via the process exit code. + tests: + - Context_WriteError_SetsErrorExitCode diff --git a/docs/reqstream/unit-path-helpers.yaml b/docs/reqstream/unit-path-helpers.yaml new file mode 100644 index 0000000..4d6fccb --- /dev/null +++ b/docs/reqstream/unit-path-helpers.yaml @@ -0,0 +1,22 @@ +--- +# Software Unit Requirements for the PathHelpers Class +# +# The PathHelpers class provides safe path-combination utilities that protect +# against path-traversal attacks by rejecting relative paths containing ".." +# or absolute paths when a relative path is expected. + +sections: + - title: PathHelpers Unit Requirements + requirements: + - id: Template-PathHelpers-SafeCombine + title: The PathHelpers class shall combine paths safely, preventing path traversal. + justification: | + Prevents path-traversal vulnerabilities when constructing file paths from + user-supplied or external inputs. Paths containing ".." or rooted paths + must be rejected to ensure the combined path remains under the base directory. + tests: + - PathHelpers_SafePathCombine_ValidPaths_CombinesCorrectly + - PathHelpers_SafePathCombine_PathTraversalWithDoubleDots_ThrowsArgumentException + - PathHelpers_SafePathCombine_DoubleDotsInMiddle_ThrowsArgumentException + - PathHelpers_SafePathCombine_AbsolutePath_ThrowsArgumentException + - PathHelpers_SafePathCombine_NestedPaths_CombinesCorrectly diff --git a/docs/reqstream/unit-program.yaml b/docs/reqstream/unit-program.yaml new file mode 100644 index 0000000..741a20f --- /dev/null +++ b/docs/reqstream/unit-program.yaml @@ -0,0 +1,45 @@ +--- +# Software Unit Requirements for the Program Class +# +# The Program class is the main entry point for the tool. It creates a Context +# from command-line arguments, dispatches to the appropriate logic based on the +# flags, and returns the exit code. + +sections: + - title: Program Unit Requirements + requirements: + - id: Template-Program-Version + title: The Program class shall support -v and --version flags to display version information. + justification: | + Users need to quickly identify the version of the tool they are using for + troubleshooting and compatibility verification. + tests: + - Program_Run_WithVersionFlag_DisplaysVersionOnly + - Program_Version_ReturnsNonEmptyString + - IntegrationTest_VersionFlag_OutputsVersion + + - id: Template-Program-Help + title: The Program class shall support -?, -h, and --help flags to display usage information. + justification: | + Users need access to command-line usage documentation without requiring + external resources. + tests: + - Program_Run_WithHelpFlag_DisplaysUsageInformation + - IntegrationTest_HelpFlag_OutputsUsageInformation + + - id: Template-Program-Validate + title: The Program class shall support --validate flag to invoke the self-validation framework. + justification: | + Provides a built-in mechanism to verify the tool is functioning correctly + in the deployment environment. + tests: + - Program_Run_WithValidateFlag_RunsValidation + - IntegrationTest_ValidateFlag_RunsValidation + + - id: Template-Program-ExitCode + title: The Program class shall return a non-zero exit code on failure. + justification: | + Callers (scripts, CI/CD pipelines) must be able to detect failure conditions + programmatically via the process exit code. + tests: + - IntegrationTest_UnknownArgument_ReturnsError diff --git a/docs/reqstream/unit-validation.yaml b/docs/reqstream/unit-validation.yaml new file mode 100644 index 0000000..aa3cb6e --- /dev/null +++ b/docs/reqstream/unit-validation.yaml @@ -0,0 +1,29 @@ +--- +# Software Unit Requirements for the Validation Class +# +# The Validation class provides the self-validation framework, running tests +# that demonstrate the tool is functioning correctly in the deployment environment. +# It supports writing results to TRX (MSTest) or JUnit XML format. + +sections: + - title: Validation Unit Requirements + requirements: + - id: Template-Validation-Run + title: The Validation class shall run self-validation tests and print a summary. + justification: | + Provides a built-in mechanism to verify the tool is functioning correctly + in the deployment environment. A summary is printed for human review. + tests: + - Validation_Run_WithSilentContext_PrintsSummary + - Validation_Run_WithSilentContext_ExitCodeIsZero + + - id: Template-Validation-Results + title: The Validation class shall write test results to a file in TRX or JUnit format. + justification: | + Enables integration with CI/CD systems that expect standard test result formats. + TRX format is compatible with MSTest; JUnit XML is compatible with many CI tools. + tests: + - Validation_Run_WithTrxResultsFile_WritesTrxFile + - Validation_Run_WithXmlResultsFile_WritesXmlFile + - IntegrationTest_ValidateWithResults_GeneratesTrxFile + - IntegrationTest_ValidateWithResults_GeneratesJUnitFile diff --git a/docs/requirements/definition.yaml b/docs/requirements/definition.yaml deleted file mode 100644 index a0f3371..0000000 --- a/docs/requirements/definition.yaml +++ /dev/null @@ -1,11 +0,0 @@ ---- -resource-path: - - docs/requirements - - docs/template -input-files: - - docs/requirements/title.txt - - docs/requirements/introduction.md - - docs/requirements/requirements.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/requirements_doc/definition.yaml b/docs/requirements_doc/definition.yaml new file mode 100644 index 0000000..0f4ccd2 --- /dev/null +++ b/docs/requirements_doc/definition.yaml @@ -0,0 +1,12 @@ +--- +resource-path: + - docs/requirements_doc + - docs/template +input-files: + - docs/requirements_doc/title.txt + - docs/requirements_doc/introduction.md + - docs/requirements_doc/requirements.md + - docs/requirements_doc/justifications.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/requirements/introduction.md b/docs/requirements_doc/introduction.md similarity index 100% rename from docs/requirements/introduction.md rename to docs/requirements_doc/introduction.md diff --git a/docs/requirements/title.txt b/docs/requirements_doc/title.txt similarity index 100% rename from docs/requirements/title.txt rename to docs/requirements_doc/title.txt diff --git a/docs/requirements_report/definition.yaml b/docs/requirements_report/definition.yaml new file mode 100644 index 0000000..918a645 --- /dev/null +++ b/docs/requirements_report/definition.yaml @@ -0,0 +1,11 @@ +--- +resource-path: + - docs/requirements_report + - docs/template +input-files: + - docs/requirements_report/title.txt + - docs/requirements_report/introduction.md + - docs/requirements_report/trace_matrix.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/tracematrix/introduction.md b/docs/requirements_report/introduction.md similarity index 100% rename from docs/tracematrix/introduction.md rename to docs/requirements_report/introduction.md diff --git a/docs/tracematrix/title.txt b/docs/requirements_report/title.txt similarity index 100% rename from docs/tracematrix/title.txt rename to docs/requirements_report/title.txt diff --git a/docs/reviewplan/definition.yaml b/docs/reviewplan/definition.yaml deleted file mode 100644 index 362a390..0000000 --- a/docs/reviewplan/definition.yaml +++ /dev/null @@ -1,11 +0,0 @@ ---- -resource-path: - - docs/reviewplan - - docs/template -input-files: - - docs/reviewplan/title.txt - - docs/reviewplan/introduction.md - - docs/reviewplan/review-plan.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/reviewreport/definition.yaml b/docs/reviewreport/definition.yaml deleted file mode 100644 index 671c73e..0000000 --- a/docs/reviewreport/definition.yaml +++ /dev/null @@ -1,11 +0,0 @@ ---- -resource-path: - - docs/reviewreport - - docs/template -input-files: - - docs/reviewreport/title.txt - - docs/reviewreport/introduction.md - - docs/reviewreport/review-report.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/tracematrix/definition.yaml b/docs/tracematrix/definition.yaml deleted file mode 100644 index ba93d57..0000000 --- a/docs/tracematrix/definition.yaml +++ /dev/null @@ -1,11 +0,0 @@ ---- -resource-path: - - docs/tracematrix - - docs/template -input-files: - - docs/tracematrix/title.txt - - docs/tracematrix/introduction.md - - docs/tracematrix/tracematrix.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/lint.bat b/lint.bat index 20109a8..f94b53d 100644 --- a/lint.bat +++ b/lint.bat @@ -22,11 +22,11 @@ call .venv\Scripts\activate.bat pip install -r pip-requirements.txt REM Run spell check -npx cspell --no-progress --no-color "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" +call npx cspell --no-progress --no-color "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" if errorlevel 1 set "LINT_ERROR=1" REM Run markdownlint check -npx markdownlint-cli2 "**/*.md" +call npx markdownlint-cli2 "**/*.md" if errorlevel 1 set "LINT_ERROR=1" REM Run yamllint check diff --git a/requirements.yaml b/requirements.yaml index 9271910..f73928f 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -1,289 +1,15 @@ -# Requirements Testing Strategy -# -# This project uses three categories of tests to verify requirements: -# -# 1. Unit Tests - Run locally via "dotnet test" -# 2. Self-Validation Tests - Run locally via "--validate" -# 3. Platform Tests - Run via CI/CD across OS/runtime matrix -# -# NOTE: Running "reqstream --enforce" with only local test results (unit tests -# and local self-validation) is expected to show some unsatisfied requirements. -# Platform-specific requirements require test results from CI/CD runs across -# the full OS and runtime matrix. -# -# Test links can include a source filter prefix (e.g. "windows@", "ubuntu@", "net8.0@", -# "dotnet8.x@") to restrict which test results count as evidence for a requirement. This -# is critical for platform and framework requirements - removing these filters invalidates -# the evidence-based proof. -# -# Source filter prefixes: -# windows@TestName - proves the test passed on a Windows platform -# ubuntu@TestName - proves the test passed on a Linux (Ubuntu) platform -# macos@TestName - proves the test passed on a macOS platform -# net8.0@TestName - proves the test passed under the .NET 8 target framework -# net9.0@TestName - proves the test passed under the .NET 9 target framework -# net10.0@TestName - proves the test passed under the .NET 10 target framework -# dotnet8.x@TestName - proves the self-validation test ran with .NET 8.x runtime -# dotnet9.x@TestName - proves the self-validation test ran with .NET 9.x runtime -# dotnet10.x@TestName - proves the self-validation test ran with .NET 10.x runtime -# --- -sections: - - title: Template DotNet Tool Requirements - sections: - - title: Command-Line Interface - requirements: - - id: Template-Cmd-Context - title: The tool shall implement a Context class for command-line argument handling. - justification: | - Provides a standardized approach to command-line argument parsing and output - handling across all DEMA Consulting DotNet Tools. - tests: - - Context_Create_NoArguments_ReturnsDefaultContext - - Context_Create_VersionFlag_SetsVersionTrue - - Context_Create_HelpFlag_SetsHelpTrue - - Context_Create_SilentFlag_SetsSilentTrue - - Context_Create_ValidateFlag_SetsValidateTrue - - Context_Create_ResultsFlag_SetsResultsFile - - Context_Create_LogFlag_OpensLogFile - - - id: Template-Cmd-Version - title: The tool shall support -v and --version flags to display version information. - justification: | - Users need to quickly identify the version of the tool they are using for - troubleshooting and compatibility verification. - tests: - - Context_Create_VersionFlag_SetsVersionTrue - - Context_Create_ShortVersionFlag_SetsVersionTrue - - Program_Run_WithVersionFlag_DisplaysVersionOnly - - Program_Version_ReturnsNonEmptyString - - IntegrationTest_VersionFlag_OutputsVersion - - - id: Template-Cmd-Help - title: The tool shall support -?, -h, and --help flags to display usage information. - justification: | - Users need access to command-line usage documentation without requiring - external resources. - tests: - - Context_Create_HelpFlag_SetsHelpTrue - - Context_Create_ShortHelpFlag_H_SetsHelpTrue - - Context_Create_ShortHelpFlag_Question_SetsHelpTrue - - Program_Run_WithHelpFlag_DisplaysUsageInformation - - IntegrationTest_HelpFlag_OutputsUsageInformation - - - id: Template-Cmd-Silent - title: The tool shall support --silent flag to suppress console output. - justification: | - Enables automated scripts and CI/CD pipelines to run the tool without - cluttering output logs. - tests: - - Context_Create_SilentFlag_SetsSilentTrue - - Context_WriteLine_Silent_DoesNotWriteToConsole - - IntegrationTest_SilentFlag_SuppressesOutput - - - id: Template-Cmd-Validate - title: The tool shall support --validate flag to run self-validation tests. - justification: | - Provides a built-in mechanism to verify the tool is functioning correctly - in the deployment environment. - tests: - - Context_Create_ValidateFlag_SetsValidateTrue - - Program_Run_WithValidateFlag_RunsValidation - - Validation_Run_WithSilentContext_PrintsSummary - - Validation_Run_WithSilentContext_ExitCodeIsZero - - IntegrationTest_ValidateFlag_RunsValidation - - - id: Template-Cmd-Results - title: The tool shall support --results flag to write validation results in TRX or JUnit format. - justification: | - Enables integration with CI/CD systems that expect standard test result formats. - tests: - - Context_Create_ResultsFlag_SetsResultsFile - - Validation_Run_WithTrxResultsFile_WritesTrxFile - - Validation_Run_WithXmlResultsFile_WritesXmlFile - - IntegrationTest_ValidateWithResults_GeneratesTrxFile - - IntegrationTest_ValidateWithResults_GeneratesJUnitFile - - - id: Template-Cmd-Log - title: The tool shall support --log flag to write output to a log file. - justification: | - Provides persistent logging for debugging and audit trails. - tests: - - Context_Create_LogFlag_OpensLogFile - - IntegrationTest_LogFlag_WritesOutputToFile - - - id: Template-Cmd-ErrorOutput - title: The tool shall write error messages to stderr. - justification: | - Error messages must be written to stderr so they remain visible to the user - without polluting stdout, which consumers may pipe or redirect for data capture. - tests: - - Context_WriteError_NotSilent_WritesToConsole - - IntegrationTest_UnknownArgument_ReturnsError - - - id: Template-Cmd-InvalidArgs - title: The tool shall reject unknown or malformed command-line arguments with a descriptive error. - justification: | - Providing clear feedback for invalid arguments helps users quickly correct - mistakes and prevents silent misconfiguration. - tests: - - Context_Create_UnknownArgument_ThrowsArgumentException - - Context_Create_LogFlag_WithoutValue_ThrowsArgumentException - - Context_Create_ResultsFlag_WithoutValue_ThrowsArgumentException - - IntegrationTest_UnknownArgument_ReturnsError - - - id: Template-Cmd-ExitCode - title: The tool shall return a non-zero exit code on failure. - justification: | - Callers (scripts, CI/CD pipelines) must be able to detect failure conditions - programmatically via the process exit code. - tests: - - Context_WriteError_SetsErrorExitCode - - IntegrationTest_UnknownArgument_ReturnsError - - - title: Platform Support - requirements: - - id: Template-Platform-Windows - title: The tool shall build and run on Windows platforms. - justification: | - DEMA Consulting tools must support Windows as a major development platform. - tests: - # Tests link to "windows" to ensure results come from Windows platform - - "windows@TemplateTool_VersionDisplay" - - "windows@TemplateTool_HelpDisplay" - - - id: Template-Platform-Linux - title: The tool shall build and run on Linux platforms. - justification: | - DEMA Consulting tools must support Linux for CI/CD and containerized environments. - tests: - # Tests link to "ubuntu" to ensure results come from Linux platform - - "ubuntu@TemplateTool_VersionDisplay" - - "ubuntu@TemplateTool_HelpDisplay" - - - id: Template-Platform-MacOS - title: The tool shall build and run on macOS platforms. - justification: | - DEMA Consulting tools must support macOS for developers using Apple platforms. - tests: - # Tests link to "macos" to ensure results come from macOS platform - - "macos@TemplateTool_VersionDisplay" - - "macos@TemplateTool_HelpDisplay" - - - id: Template-Platform-Net8 - title: The tool shall support .NET 8 runtime. - justification: | - .NET 8 is an LTS release providing long-term stability for enterprise users. - tests: - - "dotnet8.x@TemplateTool_VersionDisplay" - - "dotnet8.x@TemplateTool_HelpDisplay" - - - id: Template-Platform-Net9 - title: The tool shall support .NET 9 runtime. - justification: | - .NET 9 support enables users to leverage the latest .NET features. - tests: - - "dotnet9.x@TemplateTool_VersionDisplay" - - "dotnet9.x@TemplateTool_HelpDisplay" - - - id: Template-Platform-Net10 - title: The tool shall support .NET 10 runtime. - justification: | - .NET 10 support ensures the tool remains compatible with the latest .NET ecosystem. - tests: - - "dotnet10.x@TemplateTool_VersionDisplay" - - "dotnet10.x@TemplateTool_HelpDisplay" - - - title: OTS Software - requirements: - - id: Template-OTS-MSTest - title: MSTest shall execute unit tests and report results. - justification: | - MSTest (MSTest.TestFramework and MSTest.TestAdapter) is the unit-testing framework used - by the project. It discovers and runs all test methods and writes TRX result files that - feed into coverage reporting and requirements traceability. Passing tests confirm the - framework is functioning correctly. - tags: [ots] - tests: - - Context_Create_NoArguments_ReturnsDefaultContext - - Context_Create_VersionFlag_SetsVersionTrue - - Context_Create_HelpFlag_SetsHelpTrue - - Context_Create_SilentFlag_SetsSilentTrue - - Context_Create_ValidateFlag_SetsValidateTrue - - Context_Create_ResultsFlag_SetsResultsFile - - Context_Create_LogFlag_OpensLogFile - - Context_Create_UnknownArgument_ThrowsArgumentException - - Context_Create_ShortVersionFlag_SetsVersionTrue - - - id: Template-OTS-ReqStream - title: ReqStream shall enforce that every requirement is linked to passing test evidence. - justification: | - DemaConsulting.ReqStream processes requirements.yaml and the TRX test-result files to - produce a requirements report, justifications document, and traceability matrix. When - run with --enforce, it exits with a non-zero code if any requirement lacks test evidence, - making unproven requirements a build-breaking condition. A successful pipeline run with - --enforce proves all requirements are covered and that ReqStream is functioning. - tags: [ots] - tests: - - ReqStream_EnforcementMode - - - id: Template-OTS-BuildMark - title: BuildMark shall generate build-notes documentation from GitHub Actions metadata. - justification: | - DemaConsulting.BuildMark queries the GitHub API to capture workflow run details and - renders them as a markdown build-notes document included in the release artifacts. - It runs as part of the same CI pipeline that produces the TRX test results, so a - successful pipeline run is evidence that BuildMark executed without error. - tags: [ots] - tests: - - BuildMark_MarkdownReportGeneration - - - id: Template-OTS-VersionMark - title: VersionMark shall publish captured tool-version information. - justification: | - DemaConsulting.VersionMark reads version metadata for each dotnet tool used in the - pipeline and writes a versions markdown document included in the release artifacts. - It runs in the same CI pipeline that produces the TRX test results, so a successful - pipeline run is evidence that VersionMark executed without error. - tags: [ots] - tests: - - VersionMark_CapturesVersions - - VersionMark_GeneratesMarkdownReport - - - id: Template-OTS-SarifMark - title: SarifMark shall convert CodeQL SARIF results into a markdown report. - justification: | - DemaConsulting.SarifMark reads the SARIF output produced by CodeQL code scanning and - renders it as a human-readable markdown document included in the release artifacts. - It runs in the same CI pipeline that produces the TRX test results, so a successful - pipeline run is evidence that SarifMark executed without error. - tags: [ots] - tests: - - SarifMark_SarifReading - - SarifMark_MarkdownReportGeneration - - - id: Template-OTS-SonarMark - title: SonarMark shall generate a SonarCloud quality report. - justification: | - DemaConsulting.SonarMark retrieves quality-gate and metrics data from SonarCloud and - renders it as a markdown document included in the release artifacts. It runs in the - same CI pipeline that produces the TRX test results, so a successful pipeline run is - evidence that SonarMark executed without error. - tags: [ots] - tests: - - SonarMark_QualityGateRetrieval - - SonarMark_IssuesRetrieval - - SonarMark_HotSpotsRetrieval - - SonarMark_MarkdownReportGeneration - - - id: Template-OTS-ReviewMark - title: ReviewMark shall generate a review plan and review report from the review configuration. - justification: | - DemaConsulting.ReviewMark reads the .reviewmark.yaml configuration and the review - evidence store to produce a review plan and review report documenting file review - coverage and currency. It runs in the same CI pipeline that produces the TRX test - results, so a successful pipeline run is evidence that ReviewMark executed without error. - tags: [ots] - tests: - - ReviewMark_ReviewPlanGeneration - - ReviewMark_ReviewReportGeneration +# Root requirements file - includes all subsystem, platform, and OTS requirements +includes: + - docs/reqstream/unit-context.yaml + - docs/reqstream/unit-program.yaml + - docs/reqstream/unit-validation.yaml + - docs/reqstream/unit-path-helpers.yaml + - docs/reqstream/platform-requirements.yaml + - docs/reqstream/ots-mstest.yaml + - docs/reqstream/ots-reqstream.yaml + - docs/reqstream/ots-buildmark.yaml + - docs/reqstream/ots-versionmark.yaml + - docs/reqstream/ots-sarifmark.yaml + - docs/reqstream/ots-sonarmark.yaml + - docs/reqstream/ots-reviewmark.yaml