From 64d482f7eeee58d4e274b498310a09b8211fb85e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 24 Mar 2026 13:18:32 +0000 Subject: [PATCH 01/10] Initial plan From f2d6636c1830df791f8e3285c469854916d15027 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 00:18:23 +0000 Subject: [PATCH 02/10] Apply TemplateDotNetTool improvements (PRs #61-#74) - Add .gitattributes to enforce LF line endings (PR #71) - Rename agent files to .agent.md naming convention (PR #61/#65) - Add tools: and user-invocable: true to all agent frontmatter (PR #73) - Use kebab-case name: fields in agent frontmatter - Replace .cspell.json with .cspell.yaml (YAML format with policy comments) (PR #61/#63) - Replace .markdownlint-cli2.jsonc with .markdownlint-cli2.yaml (PR #61) - Update .yamllint.yaml ignore patterns with thirdparty dirs (PR #64) - Update lint ignore paths with better glob patterns (PR #64) - Add spell check word list policy to AGENTS.md (PR #63) - Add Spell Checking section to CONTRIBUTING.md (PR #63) - Update Defer To sections to Subagent Delegation pattern (PR #65) - Fix linting config file name references in agent files --- .cspell.json | 59 ------- .cspell.yaml | 66 ++++++++ .gitattributes | 7 + ...quality-agent.md => code-quality.agent.md} | 25 ++- .github/agents/repo-consistency-agent.md | 147 ------------------ .github/agents/repo-consistency.agent.md | 39 +++++ ...rements-agent.md => requirements.agent.md} | 21 ++- ...veloper.md => software-developer.agent.md} | 21 ++- ...al-writer.md => technical-writer.agent.md} | 23 ++- ...t-developer.md => test-developer.agent.md} | 21 ++- .markdownlint-cli2.jsonc | 15 -- .markdownlint-cli2.yaml | 37 +++++ .yamllint.yaml | 9 ++ AGENTS.md | 12 +- CONTRIBUTING.md | 10 ++ 15 files changed, 257 insertions(+), 255 deletions(-) delete mode 100644 .cspell.json create mode 100644 .cspell.yaml create mode 100644 .gitattributes rename .github/agents/{code-quality-agent.md => code-quality.agent.md} (70%) delete mode 100644 .github/agents/repo-consistency-agent.md create mode 100644 .github/agents/repo-consistency.agent.md rename .github/agents/{requirements-agent.md => requirements.agent.md} (78%) rename .github/agents/{software-developer.md => software-developer.agent.md} (74%) rename .github/agents/{technical-writer.md => technical-writer.agent.md} (68%) rename .github/agents/{test-developer.md => test-developer.agent.md} (84%) delete mode 100644 .markdownlint-cli2.jsonc create mode 100644 .markdownlint-cli2.yaml diff --git a/.cspell.json b/.cspell.json deleted file mode 100644 index 38db87d..0000000 --- a/.cspell.json +++ /dev/null @@ -1,59 +0,0 @@ -{ - "version": "0.2", - "language": "en", - "words": [ - "DEMA", - "DemaConsulting", - "ReqStream", - "reqstream", - "xunit", - "csproj", - "dotnet", - "nuget", - "demaconsulting", - "dependabot", - "YAML", - "markdownlint", - "cspell", - "yamllint", - "MSTest", - "NuGet", - "Triaging", - "sonarcloud", - "Pandoc", - "Weasyprint", - "weasyprint", - "pagetitle", - "dcterms", - "Blockquotes", - "tracematrix", - "testname", - "filepart", - "hotspots", - "CodeQL", - "SonarMark", - "SARIF", - "SarifMark", - "buildnotes", - "slnx", - "Propagatable" - ], - "ignorePaths": [ - "node_modules", - "bin", - "obj", - "*.min.js", - "*.min.css", - ".git", - "package-lock.json", - "yarn.lock", - "*.csproj", - "*.sln", - "*.slnx", - "*.dll", - "*.exe", - "*.trx", - "*.spdx.json", - "AGENT_REPORT_*.md" - ] -} diff --git a/.cspell.yaml b/.cspell.yaml new file mode 100644 index 0000000..0ead15c --- /dev/null +++ b/.cspell.yaml @@ -0,0 +1,66 @@ +--- +# Spell-Checking +# +# PURPOSE: +# - Maintain professional documentation and code quality +# - Catch spelling errors before publication +# - Support consistent technical terminology usage +# - Misspelled words should be fixed in the source +# - NEVER add a misspelled word to the 'words' list +# - PROPOSE only genuine technical terms/names as needed + +version: "0.2" +language: en + +# Project-specific technical terms and tool names +words: + - Blockquotes + - buildnotes + - CodeQL + - cspell + - csproj + - dcterms + - DEMA + - DemaConsulting + - demaconsulting + - dependabot + - dotnet + - filepart + - hotspots + - markdownlint + - MSTest + - nuget + - NuGet + - Pandoc + - pagetitle + - Propagatable + - reqstream + - ReqStream + - SARIF + - SarifMark + - SBOM + - slnx + - sonarcloud + - SonarMark + - spdx + - testname + - tracematrix + - Triaging + - Weasyprint + - weasyprint + - xunit + - YAML + - yamllint + +# Exclude common build artifacts, dependencies, and vendored third-party code +ignorePaths: + - "**/.git/**" + - "**/node_modules/**" + - "**/.venv/**" + - "**/thirdparty/**" + - "**/third-party/**" + - "**/3rd-party/**" + - "**/AGENT_REPORT_*.md" + - "**/bin/**" + - "**/obj/**" + - package-lock.json diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..2f09872 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,7 @@ +# Set default behavior: normalize line endings to LF on checkout for all text files. +# This ensures consistent SHA256 fingerprints for reviewmark across all platforms. +* text=auto eol=lf + +# Windows batch files require CRLF line endings to function correctly. +*.bat text eol=crlf +*.cmd text eol=crlf diff --git a/.github/agents/code-quality-agent.md b/.github/agents/code-quality.agent.md similarity index 70% rename from .github/agents/code-quality-agent.md rename to .github/agents/code-quality.agent.md index 5c613a2..6a18895 100644 --- a/.github/agents/code-quality-agent.md +++ b/.github/agents/code-quality.agent.md @@ -1,6 +1,8 @@ --- -name: Code Quality Agent +name: code-quality description: Ensures code quality through linting and static analysis - responsible for security, maintainability, and correctness +tools: [read, search, edit, execute, github, agent] +user-invocable: true --- # Code Quality Agent - ReqStream @@ -31,8 +33,8 @@ Ensure the project is: 1. **Build**: Zero warnings (TreatWarningsAsErrors=true) 2. **Linting**: - - markdownlint (`.markdownlint-cli2.jsonc`) - - cspell (`.cspell.json`) + - markdownlint (`.markdownlint-cli2.yaml`) + - cspell (`.cspell.yaml`) - yamllint (`.yamllint.yaml`) - dotnet format (`.editorconfig`) 3. **Static Analysis**: @@ -70,12 +72,19 @@ dotnet reqstream --requirements requirements.yaml \ lint.bat # Windows ``` -## Defer To +## Subagent Delegation -- **Requirements Agent**: For requirements quality and test linkage strategy -- **Technical Writer Agent**: For fixing documentation content -- **Software Developer Agent**: For fixing production code issues -- **Test Developer Agent**: For fixing test code issues +If requirements quality or test linkage issues are found, call the @requirements agent with the **request** to +address requirements quality and test linkage strategy and the **context** of the issues found. + +If documentation content needs fixing, call the @technical-writer agent with the **request** to fix the +documentation content and the **context** of the issues found. + +If production code issues are found, call the @software-developer agent with the **request** to fix the +production code issues and the **context** of the issues found. + +If test code issues are found, call the @test-developer agent with the **request** to fix the test code issues +and the **context** of the issues found. ## Don't diff --git a/.github/agents/repo-consistency-agent.md b/.github/agents/repo-consistency-agent.md deleted file mode 100644 index 43be335..0000000 --- a/.github/agents/repo-consistency-agent.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -name: Repo Consistency Agent -description: Ensures downstream repositories remain consistent with the TemplateDotNetTool template patterns and best practices ---- - -# Repo Consistency Agent - ReqStream - -Maintain consistency between ReqStream and the TemplateDotNetTool template at . - -## When to Invoke This Agent - -Invoke the repo-consistency-agent for: - -- Periodic reviews of ReqStream based on this template -- Checking if ReqStream follows the latest template patterns -- Identifying drift from template standards -- Recommending updates to bring projects back in sync with template - -## Responsibilities - -### Consistency Checks - -The agent reviews the following areas for consistency with the template: - -#### GitHub Configuration - -- **Issue Templates**: `.github/ISSUE_TEMPLATE/` files (bug_report.yml, feature_request.yml, config.yml) -- **Pull Request Template**: `.github/pull_request_template.md` -- **Workflow Patterns**: General structure of `.github/workflows/` (build.yaml, build_on_push.yaml, release.yaml) - - Note: Some projects may need workflow deviations for specific requirements - -#### Agent Configuration - -- **Agent Definitions**: `.github/agents/` directory structure -- **Agent Documentation**: `AGENTS.md` file listing available agents - -#### Code Structure and Patterns - -- **Context Parsing**: `Context.cs` pattern for command-line argument handling -- **Self-Validation**: `Validation.cs` pattern for built-in tests -- **Program Entry**: `Program.cs` pattern with version/help/validation routing -- **Standard Arguments**: Support for `-v`, `--version`, `-?`, `-h`, `--help`, `--silent`, `--validate`, `--results`, `--log` - -#### Documentation - -- **README Structure**: Follows template README.md pattern (badges, features, installation, - usage, structure, CI/CD, documentation, license) -- **Standard Files**: Presence and structure of: - - `CONTRIBUTING.md` - - `CODE_OF_CONDUCT.md` - - `SECURITY.md` - - `LICENSE` - -#### Quality Configuration - -- **Linting Rules**: `.cspell.json`, `.markdownlint-cli2.jsonc`, `.yamllint.yaml` - - Note: Spelling exceptions will be repository-specific -- **Editor Config**: `.editorconfig` settings (file-scoped namespaces, 4-space indent, UTF-8+BOM, LF endings) -- **Code Style**: C# code style rules and analyzer configuration - -#### Project Configuration - -- **csproj Sections**: Key sections in .csproj files: - - NuGet Tool Package Configuration - - Symbol Package Configuration - - Code Quality Configuration (TreatWarningsAsErrors, GenerateDocumentationFile, etc.) - - SBOM Configuration - - Common package references (DemaConsulting.TestResults, Microsoft.SourceLink.GitHub, analyzers) - -#### Documentation Generation - -- **Document Structure**: `docs/` directory with: - - `guide/` (user guide) - - `requirements/` (auto-generated) - - `justifications/` (auto-generated) - - `tracematrix/` (auto-generated) - - `buildnotes/` (auto-generated) - - `quality/` (auto-generated) -- **Definition Files**: `definition.yaml` files for document generation - -### Tracking Template Evolution - -To ensure downstream projects benefit from recent template improvements, review recent pull requests -merged into the template repository: - -1. **List Recent PRs**: Retrieve recently merged PRs from `demaconsulting/TemplateDotNetTool` - - Review the last 10-20 PRs to identify template improvements - -2. **Identify Propagatable Changes**: For each PR, determine if changes should apply to downstream - projects: - - Focus on structural changes (workflows, agents, configurations) over content-specific changes - - Note changes to `.github/`, linting configurations, project patterns, and documentation - structure - -3. **Check Downstream Application**: Verify if identified changes exist in the downstream project: - - Check if similar files/patterns exist in downstream - - Compare file contents between template and downstream project - - Look for similar PR titles or commit messages in downstream repository history - -4. **Recommend Missing Updates**: For changes not yet applied, include them in the consistency - review with: - - Description of the template change (reference PR number) - - Explanation of benefits for the downstream project - - Specific files or patterns that need updating - -This technique ensures downstream projects don't miss important template improvements and helps -maintain long-term consistency. - -### Review Process - -1. **Identify Differences**: Compare downstream repository structure with template -2. **Assess Impact**: Determine if differences are intentional variations or drift -3. **Recommend Updates**: Suggest specific files or patterns that should be updated -4. **Respect Customizations**: Recognize valid project-specific customizations - -### What NOT to Flag - -- Project-specific naming (tool names, package IDs, repository URLs) -- Project-specific spell check exceptions in `.cspell.json` -- Workflow variations for specific project needs -- Additional requirements or features beyond the template -- Project-specific dependencies - -## Defer To - -- **Software Developer Agent**: For implementing code changes recommended by consistency check -- **Technical Writer Agent**: For updating documentation to match template -- **Requirements Agent**: For updating requirements.yaml -- **Test Developer Agent**: For updating test patterns -- **Code Quality Agent**: For applying linting and code style changes - -## Usage Pattern - -This agent is typically invoked on downstream repositories (not on TemplateDotNetTool itself): - -1. Clone or access the downstream repository -2. Invoke repo-consistency-agent to review consistency with the TemplateDotNetTool template () -3. Review agent recommendations -4. Apply relevant changes using appropriate specialized agents -5. Test changes to ensure they don't break existing functionality - -## Key Principles - -- **Template Evolution**: As the template evolves, this agent helps downstream projects stay current -- **Respect Customization**: Not all differences are problems - some are valid customizations -- **Incremental Adoption**: Downstream projects can adopt template changes incrementally -- **Documentation**: When recommending changes, explain why they align with best practices diff --git a/.github/agents/repo-consistency.agent.md b/.github/agents/repo-consistency.agent.md new file mode 100644 index 0000000..8591e2f --- /dev/null +++ b/.github/agents/repo-consistency.agent.md @@ -0,0 +1,39 @@ +--- +name: repo-consistency +description: Ensures downstream repositories remain consistent with the TemplateDotNetTool template patterns and best practices. +tools: [read, search, edit, execute, github, agent] +user-invocable: true +--- + +# Repo Consistency Agent + +Maintain consistency between downstream projects and the TemplateDotNetTool template, ensuring repositories +benefit from template evolution while respecting project-specific customizations. + +## Reporting + +If detailed documentation of consistency analysis is needed, create a report using the filename pattern +`AGENT_REPORT_consistency_[repo_name].md` (e.g., `AGENT_REPORT_consistency_MyTool.md`) to document +consistency gaps, template evolution updates, and recommended changes for the specific repository. + +## Consistency Steps + +1. Fetch the 20 most recently merged PRs (`is:pr is:merged sort:updated-desc`) from +2. Determine the intent of the template pull requests (what changes were performed to which files) +3. Apply missing changes to this repository's files (if appropriate and with translation) + +## Don't Do These Things + +- **Never recommend changes without understanding project context** (some differences are intentional) +- **Never flag valid project-specific customizations** as consistency problems +- **Never apply template changes blindly** without assessing downstream project impact +- **Never ignore template evolution benefits** when they clearly improve downstream projects +- **Never recommend breaking changes** without migration guidance and impact assessment +- **Never skip validation** of preserved functionality after template alignment +- **Never assume all template patterns apply universally** (assess project-specific needs) + +## Key Principles + +- **Evolutionary Consistency**: Template improvements should enhance downstream projects systematically +- **Intelligent Customization Respect**: Distinguished valid customizations from unintentional drift +- **Incremental Template Adoption**: Support phased adoption of template improvements based on project capacity diff --git a/.github/agents/requirements-agent.md b/.github/agents/requirements.agent.md similarity index 78% rename from .github/agents/requirements-agent.md rename to .github/agents/requirements.agent.md index f6e0c17..41b2e14 100644 --- a/.github/agents/requirements-agent.md +++ b/.github/agents/requirements.agent.md @@ -1,6 +1,8 @@ --- -name: Requirements Agent +name: requirements description: Develops requirements and ensures appropriate test coverage - knows which requirements need unit/integration/self-validation tests +tools: [read, search, edit, execute, github, web, agent] +user-invocable: true --- # Requirements Agent - ReqStream @@ -66,12 +68,19 @@ evidence. This is critical for platform and framework requirements - **never rem Without the source filter, a test result from any platform/framework satisfies the requirement. Removing a filter invalidates the evidence for platform/framework requirements. -## Defer To +## Subagent Delegation -- **Software Developer Agent**: For implementing self-validation tests -- **Test Developer Agent**: For implementing unit and integration tests -- **Technical Writer Agent**: For documentation of requirements and processes -- **Code Quality Agent**: For verifying test quality and enforcement +If self-validation tests need implementing, call the @software-developer agent with the **request** to implement +self-validation tests and the **context** of the requirements and test strategy. + +If unit or integration tests need implementing, call the @test-developer agent with the **request** to implement +unit or integration tests and the **context** of the requirements and test scenarios. + +If documentation of requirements or processes is needed, call the @technical-writer agent with the **request** to +document requirements and processes and the **context** of the content to document. + +If test quality or enforcement needs verifying, call the @code-quality agent with the **request** to verify test +quality and enforcement and the **context** of the current state. ## Don't diff --git a/.github/agents/software-developer.md b/.github/agents/software-developer.agent.md similarity index 74% rename from .github/agents/software-developer.md rename to .github/agents/software-developer.agent.md index 2b0b374..1c84d6d 100644 --- a/.github/agents/software-developer.md +++ b/.github/agents/software-developer.agent.md @@ -1,6 +1,8 @@ --- -name: Software Developer +name: software-developer description: Writes production code and self-validation tests - targets design-for-testability and literate programming style +tools: [read, search, edit, execute, github, agent] +user-invocable: true --- # Software Developer - ReqStream @@ -66,12 +68,19 @@ var results = ProcessFile(options.InputFile); - Must support TRX/JUnit output format - Link to requirements in `requirements.yaml` -## Defer To +## Subagent Delegation -- **Requirements Agent**: For new requirement creation and test strategy -- **Test Developer Agent**: For unit and integration tests -- **Technical Writer Agent**: For documentation updates -- **Code Quality Agent**: For linting, formatting, and static analysis +If new requirements or test strategy is needed, call the @requirements agent with the **request** to create or +update requirements and the **context** of the feature being implemented. + +If unit or integration tests are needed, call the @test-developer agent with the **request** to write unit or +integration tests and the **context** of the code to be tested. + +If documentation updates are needed, call the @technical-writer agent with the **request** to update documentation +and the **context** of the changes made. + +If linting, formatting, or static analysis issues arise, call the @code-quality agent with the **request** to +fix the quality issues and the **context** of the issues found. ## Don't diff --git a/.github/agents/technical-writer.md b/.github/agents/technical-writer.agent.md similarity index 68% rename from .github/agents/technical-writer.md rename to .github/agents/technical-writer.agent.md index c84bb64..64a7e65 100644 --- a/.github/agents/technical-writer.md +++ b/.github/agents/technical-writer.agent.md @@ -1,6 +1,8 @@ --- -name: Technical Writer +name: technical-writer description: Ensures documentation is accurate and complete - knowledgeable about regulatory documentation and special document types +tools: [read, search, edit, execute, github, agent] +user-invocable: true --- # Technical Writer - ReqStream @@ -41,7 +43,7 @@ Invoke the technical-writer for: #### Linting Requirements - **markdownlint**: Style and structure compliance -- **cspell**: Spelling (add technical terms to `.cspell.json`) +- **cspell**: Spelling (add technical terms to `.cspell.yaml`) - **yamllint**: YAML file validation ### Regulatory Documentation @@ -52,12 +54,19 @@ For documents requiring regulatory compliance: - Appropriate detail level for audience - Traceability to requirements where applicable -## Defer To +## Subagent Delegation -- **Requirements Agent**: For requirements.yaml content and test linkage -- **Software Developer Agent**: For code examples and self-validation behavior -- **Test Developer Agent**: For test documentation -- **Code Quality Agent**: For running linters and fixing lint issues +If requirements.yaml content or test linkage needs updating, call the @requirements agent with the **request** to +update requirements and test linkage and the **context** of the documentation changes. + +If code examples or self-validation behavior needs clarifying, call the @software-developer agent with the +**request** to clarify code examples or self-validation behavior and the **context** of the documentation need. + +If test documentation needs updating, call the @test-developer agent with the **request** to update test +documentation and the **context** of what needs documenting. + +If linting issues need fixing, call the @code-quality agent with the **request** to fix lint issues and the +**context** of the linting errors found. ## Don't diff --git a/.github/agents/test-developer.md b/.github/agents/test-developer.agent.md similarity index 84% rename from .github/agents/test-developer.md rename to .github/agents/test-developer.agent.md index 67f58dd..2b3c6fa 100644 --- a/.github/agents/test-developer.md +++ b/.github/agents/test-developer.agent.md @@ -1,6 +1,8 @@ --- -name: Test Developer +name: test-developer description: Writes unit and integration tests following AAA pattern - clear documentation of what's tested and proved +tools: [read, search, edit, execute, github, agent] +user-invocable: true --- # Test Developer - ReqStream @@ -132,12 +134,19 @@ Common anti-patterns to avoid (not exhaustive): // ✅ Good: Assert.StartsWith("prefix", value); ``` -## Defer To +## Subagent Delegation -- **Requirements Agent**: For test strategy and coverage requirements -- **Software Developer Agent**: For self-validation tests and production code issues -- **Technical Writer Agent**: For test documentation in markdown -- **Code Quality Agent**: For test linting and static analysis +If test strategy or coverage requirements need defining, call the @requirements agent with the **request** to +define test strategy and coverage requirements and the **context** of the feature being tested. + +If self-validation tests or production code issues arise, call the @software-developer agent with the **request** +to implement self-validation tests or fix production code and the **context** of the issue found. + +If test documentation in markdown needs updating, call the @technical-writer agent with the **request** to +update test documentation and the **context** of the tests written. + +If test linting or static analysis issues arise, call the @code-quality agent with the **request** to fix test +linting or static analysis issues and the **context** of the issues found. ## Don't diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc deleted file mode 100644 index a46ee1a..0000000 --- a/.markdownlint-cli2.jsonc +++ /dev/null @@ -1,15 +0,0 @@ -{ - "config": { - "default": true, - "MD003": { "style": "atx" }, - "MD007": { "indent": 2 }, - "MD013": { "line_length": 120 }, - "MD025": false, - "MD033": false, - "MD041": false - }, - "ignores": [ - "node_modules", - "**/AGENT_REPORT_*.md" - ] -} diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000..ece8b40 --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,37 @@ +--- +# Markdownlint configuration for ReqStream +# See: https://github.com/DavidAnson/markdownlint-cli2 + +config: + default: true + + # Use ATX-style headers (# Header) + MD003: + style: atx + + # Unordered list indentation + MD007: + indent: 2 + + # Line length (120 chars to allow for URLs) + MD013: + line_length: 120 + + # Allow multiple top-level headers (for fragments) + MD025: false + + # Allow inline HTML + MD033: false + + # Allow documents without top-level header (for fragments) + MD041: false + +# Exclude common build artifacts, dependencies, and vendored third-party code +ignores: + - "**/.git/**" + - "**/node_modules/**" + - "**/.venv/**" + - "**/thirdparty/**" + - "**/third-party/**" + - "**/3rd-party/**" + - "**/AGENT_REPORT_*.md" diff --git a/.yamllint.yaml b/.yamllint.yaml index 446fdce..d58cdd3 100644 --- a/.yamllint.yaml +++ b/.yamllint.yaml @@ -4,6 +4,15 @@ extends: default +# Exclude common build artifacts, dependencies, and vendored third-party code +ignore: | + .git/ + node_modules/ + .venv/ + thirdparty/ + third-party/ + 3rd-party/ + rules: # Allow 'on:' in GitHub Actions workflows (not a boolean value) truthy: diff --git a/AGENTS.md b/AGENTS.md index 07447b4..e12f90a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,7 +32,17 @@ written in YAML files. - **`requirements.yaml`** - All requirements with test linkage (enforced via `dotnet reqstream --enforce`) - **`.editorconfig`** - Code style (file-scoped namespaces, 4-space indent, UTF-8, LF endings) -- **`.cspell.json`, `.markdownlint-cli2.jsonc`, `.yamllint.yaml`** - Linting configs +- **`.cspell.yaml`, `.markdownlint-cli2.yaml`, `.yamllint.yaml`** - Linting configs + +### Spell check word list policy + +**Never** add a word to the `.cspell.yaml` word list in order to silence a spell-checking failure. +Doing so defeats the purpose of spell-checking and reduces the quality of the repository. + +- If cspell flags a word that is **misspelled**, fix the spelling in the source file. +- If cspell flags a word that is a **genuine technical term** (tool name, project identifier, etc.) and is + spelled correctly, raise a **proposal** (e.g. comment in a pull request) explaining why the word + should be added. The proposal must be reviewed and approved before the word is added to the list. ## Requirements diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 459c02c..53b33d1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -176,6 +176,16 @@ cspell "**/*.md" "**/*.cs" yamllint . ``` +### Spell Checking + +All files are spell-checked using cspell. **Never** add a word to the `.cspell.yaml` word list in order to silence a +spell-checking failure. Doing so defeats the purpose of spell-checking and reduces the quality of the repository. + +- If cspell flags a word that is **misspelled**, fix the spelling in the source file. +- If cspell flags a word that is a **genuine technical term** (tool name, project identifier, etc.) and is spelled + correctly, raise a **proposal** (e.g. comment in a pull request) explaining why the word should be added. The + proposal must be reviewed and approved before the word is added to the list. + ## Pull Request Process 1. **Update documentation** if your changes affect usage or behavior From 68bc0715544d29662e19c77dcf0dfb56e7691292 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 00:20:04 +0000 Subject: [PATCH 03/10] Fix review comments: update agent file extension reference and line lengths - Update .agent.md extension references in AGENTS.md and technical-writer.agent.md - Remove 'Propagatable' from .cspell.yaml (not used in ReqStream) - Fix MD013 line length violations in AGENTS.md and technical-writer.agent.md --- .cspell.yaml | 1 - .github/agents/technical-writer.agent.md | 3 ++- AGENTS.md | 3 ++- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.cspell.yaml b/.cspell.yaml index 0ead15c..2b1ea78 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -33,7 +33,6 @@ words: - NuGet - Pandoc - pagetitle - - Propagatable - reqstream - ReqStream - SARIF diff --git a/.github/agents/technical-writer.agent.md b/.github/agents/technical-writer.agent.md index 64a7e65..7013209 100644 --- a/.github/agents/technical-writer.agent.md +++ b/.github/agents/technical-writer.agent.md @@ -36,7 +36,8 @@ Invoke the technical-writer for: - **All markdown files**: Use reference-style links `[text][ref]` with `[ref]: url` at document end - **Exceptions**: - **README.md**: Use absolute URLs in the links (shipped in NuGet package) - - **AI agent markdown files** (`.github/agents/*.md`): Use inline links `[text](url)` so URLs are visible in agent context + - **AI agent markdown files** (`.github/agents/*.agent.md`): Use inline links `[text](url)` so + URLs are visible in agent context - Max 120 characters per line - Lists require blank lines (MD032) diff --git a/AGENTS.md b/AGENTS.md index e12f90a..3f6c503 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -118,7 +118,8 @@ build.bat # Windows ## Markdown Link Style -- **AI agent markdown files** (`.github/agents/*.md`): Use inline links `[text](url)` so URLs are visible in agent context +- **AI agent markdown files** (`.github/agents/*.agent.md`): Use inline links `[text](url)` so + URLs are visible in agent context - **README.md**: Use absolute URLs (shipped in NuGet package) - **All other markdown files**: Use reference-style links `[text][ref]` with `[ref]: url` at document end From d2f95523863f4a9e65e1b0554207ab058dd3beb7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 00:21:29 +0000 Subject: [PATCH 04/10] Remove unused spdx from cspell word list --- .cspell.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/.cspell.yaml b/.cspell.yaml index 2b1ea78..0ad3696 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -41,7 +41,6 @@ words: - slnx - sonarcloud - SonarMark - - spdx - testname - tracematrix - Triaging From 48d74ac6a8c2f83e58e8e27122b1f4123006c600 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 01:17:53 +0000 Subject: [PATCH 05/10] Apply template consistency updates from TemplateDotNetTool PRs #54-#74 Apply all missing changes from the TemplateDotNetTool template to bring ReqStream into consistency with the latest template patterns. Changes applied from PRs #58-#74: PR #58 (ReviewMark integration): - Add .reviewmark.yaml with ReqStream-specific review sets - Add pip-requirements.txt (yamllint==1.38.0) - Update lint.sh/lint.bat to use Python venv + pip pattern - Update package.json with pinned cspell and markdownlint-cli2 devDependencies - Add demaconsulting.reviewmark to .config/dotnet-tools.json - Add reviewmark entry to .versionmark.yaml PR #59 (Add Code Review Agent to AGENTS.md invocation rules): - Add code-review agent to AGENTS.md available agents list - Add new .github/agents/code-review.agent.md PR #61 (Linting modernization and agent file standardization): - Update .markdownlint-cli2.yaml with PURPOSE/DO NOT MODIFY header - Update .yamllint.yaml with PURPOSE/DO NOT MODIFY header - Remove check-keys from yamllint truthy rule (aligns with template) PR #63 (enforce cspell word list policy): - Update .cspell.yaml header comment (NEVER add misspelled word) - Add missing technical terms to cspell word list (reviewmark, ReviewMark, versionmark, VersionMark, buildmark, BuildMark, gitattributes, etc.) PR #64 (Align lint YAML configs): - Apply standardized headers to markdownlint and yamllint configs PR #65-#67, #70-#73 (Agent synchronization): - Update code-quality.agent.md to template version (comprehensive content) - Update agent frontmatter descriptions to match shorter template pattern - Update repo-consistency agent and requirements, software-developer, technical-writer, test-developer agents PR #71 (.gitattributes LF line endings): - .gitattributes already had correct content PR #72 (Simplify repo-consistency agent): - repo-consistency.agent.md already aligned PR #54 (Various improvements): - Update .versionmark.yaml regex patterns to support pre-release versions - Update .gitignore to match template structure CONTRIBUTING.md: - Rewrite to match template standards with ReqStream-specific translation - Add dotnet tool restore step, XML documentation section - Add comprehensive testing guidelines with MSTest v4 assertions - Add requirements management section --- .config/dotnet-tools.json | 6 + .cspell.yaml | 13 + .github/agents/code-quality.agent.md | 242 ++++++++++++---- .github/agents/code-review.agent.md | 46 +++ .github/agents/requirements.agent.md | 2 +- .github/agents/software-developer.agent.md | 2 +- .github/agents/technical-writer.agent.md | 2 +- .github/agents/test-developer.agent.md | 2 +- .gitignore | 127 ++++----- .markdownlint-cli2.yaml | 24 +- .reviewmark.yaml | 59 ++++ .versionmark.yaml | 21 +- .yamllint.yaml | 14 +- AGENTS.md | 2 + CONTRIBUTING.md | 310 +++++++++++++-------- lint.bat | 46 ++- lint.sh | 41 ++- package.json | 2 + pip-requirements.txt | 1 + 19 files changed, 654 insertions(+), 308 deletions(-) create mode 100644 .github/agents/code-review.agent.md create mode 100644 .reviewmark.yaml create mode 100644 pip-requirements.txt diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index a3c61a7..116ebf8 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -43,6 +43,12 @@ "commands": [ "versionmark" ] + }, + "demaconsulting.reviewmark": { + "version": "0.1.0", + "commands": [ + "reviewmark" + ] } } } \ No newline at end of file diff --git a/.cspell.yaml b/.cspell.yaml index 0ad3696..9740ad9 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -15,8 +15,12 @@ language: en # Project-specific technical terms and tool names words: - Blockquotes + - buildmark + - BuildMark - buildnotes + - camelcase - CodeQL + - copilot - cspell - csproj - dcterms @@ -24,26 +28,35 @@ words: - DemaConsulting - demaconsulting - dependabot + - Dependabot - dotnet + - editorconfig - filepart + - gitattributes - hotspots - markdownlint - MSTest - nuget - NuGet + - nupkg - Pandoc - pagetitle - reqstream - ReqStream + - reviewmark + - ReviewMark - SARIF - SarifMark - SBOM - slnx + - snupkg - sonarcloud - SonarMark - testname - tracematrix - Triaging + - versionmark + - VersionMark - Weasyprint - weasyprint - xunit diff --git a/.github/agents/code-quality.agent.md b/.github/agents/code-quality.agent.md index 6a18895..da5ed78 100644 --- a/.github/agents/code-quality.agent.md +++ b/.github/agents/code-quality.agent.md @@ -1,94 +1,216 @@ --- name: code-quality -description: Ensures code quality through linting and static analysis - responsible for security, maintainability, and correctness +description: Ensures code quality through comprehensive linting and static analysis. tools: [read, search, edit, execute, github, agent] user-invocable: true --- -# Code Quality Agent - ReqStream +# Code Quality Agent -Enforce quality standards through linting, static analysis, and security scanning. +Enforce comprehensive quality standards through linting, static analysis, +security scanning, and Continuous Compliance gate verification. + +## Reporting + +If detailed documentation of code quality analysis is needed, create a report using the +filename pattern `AGENT_REPORT_quality_analysis.md` to document quality metrics, +identified patterns, and improvement recommendations. ## When to Invoke This Agent -Invoke the code-quality-agent for: +Use the Code Quality Agent for: + +- Enforcing all quality gates before merge/release +- Running and resolving linting issues across all file types +- Ensuring static analysis passes with zero blockers +- Verifying security scanning results and addressing vulnerabilities +- Validating Continuous Compliance requirements +- Maintaining lint scripts and linting tool infrastructure +- Troubleshooting quality gate failures in CI/CD + +## Primary Responsibilities -- Running and fixing linting issues (markdown, YAML, spell check, code formatting) -- Ensuring static analysis passes with zero warnings -- Verifying code security -- Enforcing quality gates before merging -- Validating the project does what it claims to do +**Quality Enforcement Context**: Code quality is enforced through CI pipelines +and automated workflows. Your role is to analyze, validate, and ensure quality +standards are met using existing tools and infrastructure, not to create new +enforcement mechanisms or helper scripts. -## Responsibilities +### Comprehensive Quality Gate Enforcement -### Primary Responsibility +The project MUST be: -Ensure the project is: +- **Secure**: Zero security vulnerabilities (CodeQL, SonarQube) +- **Maintainable**: Clean, formatted, documented code with zero warnings +- **Compliant**: Requirements traceability enforced, file reviews current +- **Correct**: Does what requirements specify with passing tests -- **Secure**: No security vulnerabilities -- **Maintainable**: Clean, well-formatted, documented code -- **Correct**: Does what it claims to do (requirements met) +### Universal Quality Gates (ALL Must Pass) -### Quality Gates (ALL Must Pass) +#### 1. Linting Standards (Zero Tolerance) + +**Primary Interface**: Use the comprehensive linting scripts for all routine checks: + +```bash +# Run comprehensive linting suite +./lint.sh # Unix/Linux/macOS +# or +lint.bat # Windows +``` -1. **Build**: Zero warnings (TreatWarningsAsErrors=true) -2. **Linting**: - - markdownlint (`.markdownlint-cli2.yaml`) - - cspell (`.cspell.yaml`) - - yamllint (`.yamllint.yaml`) - - dotnet format (`.editorconfig`) -3. **Static Analysis**: - - Microsoft.CodeAnalysis.NetAnalyzers - - SonarAnalyzer.CSharp -4. **Requirements Traceability**: - - `dotnet reqstream --requirements requirements.yaml --tests "test-results/**/*.trx" --enforce` -5. **Tests**: All validation tests passing +**Note**: The @code-quality agent is responsible for maintaining the `lint.sh`/`lint.bat` scripts. -### ReqStream-Specific +#### 2. Build Quality (Zero Warnings) -- **XML Docs**: Enforce on ALL members (public/internal/private) -- **Code Style**: Verify `.editorconfig` compliance -- **Test Naming**: Check `ReqStream_*` pattern for self-validation tests +All builds must be configured to treat warnings as errors. +This ensures that compiler warnings are addressed immediately rather than accumulating as technical debt. -### Commands to Run +#### 3. Static Analysis (Zero Blockers) + +- **SonarQube/SonarCloud**: Code quality and security analysis +- **CodeQL**: Security vulnerability scanning (SARIF output) +- **Language Analyzers**: Microsoft.CodeAnalysis.NetAnalyzers, SonarAnalyzer.CSharp +- **Custom Rules**: Project-specific quality rules + +#### 4. Continuous Compliance Verification ```bash -# Code formatting -dotnet format --verify-no-changes +# Requirements traceability enforcement +dotnet reqstream \ + --requirements requirements.yaml \ + --tests "test-results/**/*.trx" \ + --enforce + +# File review status enforcement (uses .reviewmark.yaml) +dotnet reviewmark --enforce +``` + +#### 5. Test Quality & Coverage + +- All tests must pass (zero failures) +- Requirements coverage enforced (no uncovered requirements) +- Test result artifacts properly generated (TRX, JUnit XML) + +## Comprehensive Tool Configuration + +**The @code-quality agent is responsible for maintaining the repository's linting +infrastructure, specifically the `lint.sh`/`lint.bat` scripts.** -# Build with zero warnings -dotnet build --configuration Release +### Lint Script Maintenance -# Run validation tests -dotnet run --project src/DemaConsulting.ReqStream \ - --configuration Release --framework net10.0 --no-build -- --validate +When updating tool versions or maintaining linting infrastructure, +modify the lint scripts: -# Requirements enforcement -dotnet reqstream --requirements requirements.yaml \ - --tests "test-results/**/*.trx" --enforce +- **`lint.sh`** - Unix/Linux/macOS comprehensive linting script +- **`lint.bat`** - Windows comprehensive linting script -# Run all linters -./lint.sh # Linux/macOS -lint.bat # Windows +**IMPORTANT**: Modifications should be limited to tool version updates, +path corrections, or infrastructure improvements. Do not modify enforcement +standards, rule configurations, or quality thresholds as these define +compliance requirements. + +These scripts automatically handle: + +- Node.js tool installation (markdownlint-cli2, cspell) +- Python virtual environment setup and yamllint installation +- Tool execution with proper error handling and reporting + +### Static Analysis Integration + +#### SonarQube Quality Profile + +- **Reliability**: A rating (zero bugs) +- **Security**: A rating (zero vulnerabilities) +- **Maintainability**: A rating (zero code smells for new code) +- **Coverage**: Minimum threshold (typically 80%+ for new code) +- **Duplication**: Maximum threshold (typically <3% for new code) + +#### CodeQL Security Scanning + +- **Schedule**: On every push and pull request +- **Language Coverage**: All supported languages in repository +- **SARIF Output**: Integration with GitHub Security tab +- **Blocking**: Pipeline fails on HIGH/CRITICAL findings + +## Quality Gate Execution Workflow + +### 1. Pre-Merge Quality Gates + +```bash +# Run comprehensive linting suite +./lint.sh # Unix/Linux/macOS +# or +lint.bat # Windows + +# Build with warnings as errors +dotnet build --configuration Release --no-restore /p:TreatWarningsAsErrors=true + +# Run static analysis +dotnet sonarscanner begin /k:"project-key" +dotnet build +dotnet test --collect:"XPlat Code Coverage" +dotnet sonarscanner end + +# Verify requirements compliance +dotnet reqstream --requirements requirements.yaml --tests "**/*.trx" --enforce ``` -## Subagent Delegation +### 2. Security Gate Validation -If requirements quality or test linkage issues are found, call the @requirements agent with the **request** to -address requirements quality and test linkage strategy and the **context** of the issues found. +```bash +# CodeQL analysis (automated in GitHub Actions) +codeql database create --language=csharp +codeql database analyze --format=sarif-latest --output=results.sarif -If documentation content needs fixing, call the @technical-writer agent with the **request** to fix the -documentation content and the **context** of the issues found. +# Dependency vulnerability scanning +dotnet list package --vulnerable --include-transitive +npm audit --audit-level=moderate # if Node.js dependencies +``` -If production code issues are found, call the @software-developer agent with the **request** to fix the -production code issues and the **context** of the issues found. +### 3. Documentation & Compliance Gates -If test code issues are found, call the @test-developer agent with the **request** to fix the test code issues -and the **context** of the issues found. +```bash +# File review status validation +dotnet reviewmark --definition .reviewmark.yaml --enforce -## Don't +# Generate compliance documentation +dotnet buildmark --tools tools.yaml --output docs/build_notes.md +dotnet reqstream --report docs/requirements/requirements.md --justifications docs/justifications/justifications.md +``` -- Disable quality checks to make builds pass -- Ignore security warnings -- Skip enforcement of requirements traceability -- Change functional code without consulting appropriate developer agent +## Cross-Agent Coordination + +### Hand-off to Other Agents + +- If code quality issues need to be fixed, then call the @software-developer agent with the **request** to fix code + quality, security, or linting issues with **context** of specific quality gate failures and + **additional instructions** to maintain coding standards. +- If test coverage needs improvement or tests are failing, then call the @test-developer agent with the **request** + to improve test coverage or fix failing tests with **context** of current coverage metrics and failing test details. +- If documentation linting fails or documentation is missing, then call the @technical-writer agent with the + **request** to fix documentation linting or generate missing docs with **context** of specific linting failures and + documentation gaps. +- If requirements traceability fails, then call the @requirements agent with the **request** to address requirements + traceability failures with **context** of enforcement errors and missing test linkages. + +## Compliance Verification Checklist + +### Before Approving Any Changes + +1. **Linting**: All linting tools pass (markdownlint, cspell, yamllint, language linters) +2. **Build**: Zero warnings, zero errors in all configurations +3. **Static Analysis**: SonarQube quality gate GREEN, CodeQL no HIGH/CRITICAL findings +4. **Requirements**: ReqStream enforcement passes, all requirements covered +5. **Tests**: All tests pass, adequate coverage maintained +6. **Documentation**: All generated docs current, spell-check passes +7. **Security**: No vulnerability findings in dependencies or code +8. **File Reviews**: All reviewable files have current reviews (if applicable) + +## Don't Do These Things + +- **Never disable quality checks** to make builds pass (fix the underlying issue) +- **Never ignore security warnings** without documented risk acceptance +- **Never skip requirements enforcement** for "quick fixes" +- **Never modify functional code** without appropriate developer agent involvement +- **Never lower quality thresholds** without compliance team approval +- **Never commit with linting failures** (CI should block this) +- **Never bypass static analysis** findings without documented justification diff --git a/.github/agents/code-review.agent.md b/.github/agents/code-review.agent.md new file mode 100644 index 0000000..fb01a20 --- /dev/null +++ b/.github/agents/code-review.agent.md @@ -0,0 +1,46 @@ +--- +name: code-review +description: Assists in performing formal file reviews. +tools: [read, search, edit, execute, github, web, agent] +user-invocable: true +--- + +# Code Review Agent + +Execute comprehensive code reviews with emphasis on structured compliance verification and file review status +requirements. + +## Reporting + +Create a report using the filename pattern `AGENT_REPORT_code_review_[review-set].md` +(e.g., `AGENT_REPORT_code_review_auth-module.md`) to document review criteria, identified issues, and recommendations +for the specific review-set. + +## Review Steps + +1. Download the + + to get the checklist to fill in +2. Use `dotnet reviewmark --elaborate [review-set]` to get the files to review +3. Review the files all together +4. Populate the checklist with the findings to make the report + +## Hand-off to Other Agents + +Only attempt to apply review fixes if requested. + +- If code quality, logic, or structural issues need fixing, call the @software-developer agent +- If test coverage gaps or quality issues are identified, call the @test-developer agent +- If documentation accuracy or completeness issues are found, call the @technical-writer agent +- If quality gate verification is needed after fixes, call the @code-quality agent +- If requirements traceability issues are discovered, call the @requirements agent + +## Don't Do These Things + +- **Never modify code during review** (document findings only, delegate fixes) +- **Never skip applicable checklist items** (comprehensive review required) +- **Never approve reviews with unresolved critical findings** +- **Never bypass review status requirements** for compliance +- **Never conduct reviews without proper documentation** +- **Never ignore security or compliance findings** +- **Never approve without verifying all quality gates** diff --git a/.github/agents/requirements.agent.md b/.github/agents/requirements.agent.md index 41b2e14..3982e6f 100644 --- a/.github/agents/requirements.agent.md +++ b/.github/agents/requirements.agent.md @@ -1,6 +1,6 @@ --- name: requirements -description: Develops requirements and ensures appropriate test coverage - knows which requirements need unit/integration/self-validation tests +description: Develops requirements and ensures appropriate test coverage. tools: [read, search, edit, execute, github, web, agent] user-invocable: true --- diff --git a/.github/agents/software-developer.agent.md b/.github/agents/software-developer.agent.md index 1c84d6d..6c4338a 100644 --- a/.github/agents/software-developer.agent.md +++ b/.github/agents/software-developer.agent.md @@ -1,6 +1,6 @@ --- name: software-developer -description: Writes production code and self-validation tests - targets design-for-testability and literate programming style +description: Writes production code and self-validation tests. tools: [read, search, edit, execute, github, agent] user-invocable: true --- diff --git a/.github/agents/technical-writer.agent.md b/.github/agents/technical-writer.agent.md index 7013209..30d2f5b 100644 --- a/.github/agents/technical-writer.agent.md +++ b/.github/agents/technical-writer.agent.md @@ -1,6 +1,6 @@ --- name: technical-writer -description: Ensures documentation is accurate and complete - knowledgeable about regulatory documentation and special document types +description: Ensures documentation is accurate and complete. tools: [read, search, edit, execute, github, agent] user-invocable: true --- diff --git a/.github/agents/test-developer.agent.md b/.github/agents/test-developer.agent.md index 2b3c6fa..a287b0b 100644 --- a/.github/agents/test-developer.agent.md +++ b/.github/agents/test-developer.agent.md @@ -1,6 +1,6 @@ --- name: test-developer -description: Writes unit and integration tests following AAA pattern - clear documentation of what's tested and proved +description: Writes unit and integration tests. tools: [read, search, edit, execute, github, agent] user-invocable: true --- diff --git a/.gitignore b/.gitignore index 1e5419d..ec91165 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,19 @@ +## Ignore Visual Studio temporary files, build results, and +## files generated by popular Visual Studio add-ons. + +# User-specific files +*.rsuser +*.suo +*.user +*.userosscache +*.sln.docstates + +# User-specific files (MonoDevelop/Xamarin Studio) +*.userprefs + +# Mono auto generated files +mono_crash.* + # Build results [Dd]ebug/ [Dd]ebugPublic/ @@ -5,6 +21,7 @@ [Rr]eleases/ x64/ x86/ +[Ww][Ii][Nn]32/ [Aa][Rr][Mm]/ [Aa][Rr][Mm]64/ bld/ @@ -16,110 +33,60 @@ bld/ # Visual Studio cache/options directory .vs/ -# Visual Studio Code directory +# Visual Studio Code .vscode/* +!.vscode/settings.json !.vscode/tasks.json +!.vscode/launch.json +!.vscode/extensions.json -# Rider directory -.idea/ - -# User-specific files -*.rsuser -*.suo -*.user -*.userosscache -*.sln.docstates - -# Mono Auto Generated Files -mono_crash.* - -# Windows specific patterns -[Ww][Ii][Nn]32/ +# ReSharper is a .NET coding add-in +_ReSharper*/ +*.[Rr]e[Ss]harper +*.DotSettings.user -# .NET Core -project.lock.json -project.fragment.lock.json -artifacts/ +# JetBrains Rider +.idea/ +*.sln.iml # NuGet Packages *.nupkg *.snupkg **/packages/* -!**/packages/build/ -# Test Results +# MSTest test Results [Tt]est[Rr]esult*/ [Bb]uild[Ll]og.* + +# NUNIT *.VisualState.xml TestResult.xml +nunit-*.xml + +# Build Results of an ATL Project [Dd]ebugPS/ [Rr]eleasePS/ -coverage*.json -coverage*.xml -coverage*.info - -# Files built by Visual Studio -*_i.c -*_p.c -*_h.h -*.ilk -*.meta -*.obj -*.iobj -*.pch -*.pdb -*.ipdb -*.pgc -*.pgd -*.rsp -*.sbr -*.tlb -*.tli -*.tlh -*.tmp -*.tmp_proj -*_wpftmp.csproj -*.log -*.vspscc -*.vssscc -.builds -*.pidb -*.svclog -*.scc - -# Visual C++ cache files -ipch/ -*.aps -*.ncb -*.opendb -*.opensdf -*.sdf -*.cachefile -*.VC.db -*.VC.VC.opendb - -# ReSharper -_ReSharper*/ -*.[Rr]e[Ss]harper -*.DotSettings.user - -# JetBrains Rider -.idea/ -*.sln.iml +dlldata.c -# macOS -.DS_Store +# Benchmark Results +BenchmarkDotNet.Artifacts/ -# Windows -Thumbs.db -ehthumbs.db -Desktop.ini +# .NET +project.lock.json +project.fragment.lock.json +artifacts/ # Node.js node_modules/ package-lock.json npm-debug.log +# Python +__pycache__/ +*.py[cod] +*$py.class +.venv/ + # Generated documentation docs/**/*.html docs/**/*.pdf diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index ece8b40..04f1f80 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -1,26 +1,36 @@ --- -# Markdownlint configuration for ReqStream -# See: https://github.com/DavidAnson/markdownlint-cli2 +# Markdown Linting Standards +# +# PURPOSE: +# - Maintain professional technical documentation standards +# - Ensure consistent formatting for readability and maintenance +# - Support automated documentation generation and publishing +# +# DO NOT MODIFY: These rules represent coding standards +# - If files fail linting, fix the files to meet these standards +# - Do not relax rules to accommodate existing non-compliant files +# - Consistency across repositories is critical for documentation quality config: + # Enable all default rules default: true - # Use ATX-style headers (# Header) + # Require ATX-style headers (# Header) instead of Setext-style MD003: style: atx - # Unordered list indentation + # Set consistent indentation for nested lists MD007: indent: 2 - # Line length (120 chars to allow for URLs) + # Allow longer lines for URLs and technical content MD013: line_length: 120 - # Allow multiple top-level headers (for fragments) + # Allow multiple top-level headers per document MD025: false - # Allow inline HTML + # Allow inline HTML for enhanced documentation MD033: false # Allow documents without top-level header (for fragments) diff --git a/.reviewmark.yaml b/.reviewmark.yaml new file mode 100644 index 0000000..8bf2eda --- /dev/null +++ b/.reviewmark.yaml @@ -0,0 +1,59 @@ +--- +# 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 following software unit boundaries. + +# Patterns identifying all files that require review. +# Processed in order; prefix a pattern with '!' to exclude. +needs-review: + - "**/*.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. +# Note: The 'reviews' branch must be created and populated with review evidence PDFs +# and an index.json before enforcement (--enforce flag) can be enabled in the pipeline. +evidence-source: + type: url + location: https://raw.githubusercontent.com/demaconsulting/ReqStream/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: + # Software unit reviews - one per class + - id: ReqStream-Context + title: Review of ReqStream Context Unit + paths: + - "src/**/Context.cs" + - "test/**/ContextTests.cs" + + - id: ReqStream-Program + title: Review of ReqStream Program Unit + paths: + - "src/**/Program.cs" + - "test/**/ProgramTests.cs" + + - id: ReqStream-Validation + title: Review of ReqStream Validation Unit + paths: + - "src/**/Validation.cs" + + - id: ReqStream-Requirements + title: Review of ReqStream Requirements Unit + paths: + - "src/**/Requirement.cs" + - "src/**/Requirements.cs" + - "src/**/Section.cs" + - "test/**/RequirementsReadTests.cs" + - "test/**/RequirementsExportTests.cs" + + - id: ReqStream-TraceMatrix + title: Review of ReqStream TraceMatrix Unit + paths: + - "src/**/TraceMatrix.cs" + - "test/**/TraceMatrixTests.cs" + - "test/**/TraceMatrixReadTests.cs" + - "test/**/TraceMatrixExportTests.cs" diff --git a/.versionmark.yaml b/.versionmark.yaml index bb4d955..74d29fb 100644 --- a/.versionmark.yaml +++ b/.versionmark.yaml @@ -27,40 +27,45 @@ tools: # SonarScanner for .NET (from dotnet tool list) dotnet-sonarscanner: command: dotnet tool list - regex: '(?i)dotnet-sonarscanner\s+(?\d+\.\d+\.\d+)' + regex: '(?i)dotnet-sonarscanner\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # Pandoc (DemaConsulting.PandocTool from dotnet tool list) pandoc: command: dotnet tool list - regex: '(?i)demaconsulting\.pandoctool\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.pandoctool\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # WeasyPrint (DemaConsulting.WeasyPrintTool from dotnet tool list) weasyprint: command: dotnet tool list - regex: '(?i)demaconsulting\.weasyprinttool\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.weasyprinttool\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # SarifMark (DemaConsulting.SarifMark from dotnet tool list) sarifmark: command: dotnet tool list - regex: '(?i)demaconsulting\.sarifmark\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.sarifmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # SonarMark (DemaConsulting.SonarMark from dotnet tool list) sonarmark: command: dotnet tool list - regex: '(?i)demaconsulting\.sonarmark\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.sonarmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # ReqStream (DemaConsulting.ReqStream from dotnet tool list --global) # Note: ReqStream is installed globally in integration-test and build-docs jobs reqstream: command: dotnet tool list --global - regex: '(?i)demaconsulting\.reqstream\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.reqstream\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # BuildMark (DemaConsulting.BuildMark from dotnet tool list) buildmark: command: dotnet tool list - regex: '(?i)demaconsulting\.buildmark\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.buildmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # VersionMark (DemaConsulting.VersionMark from dotnet tool list) versionmark: command: dotnet tool list - regex: '(?i)demaconsulting\.versionmark\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.versionmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' + + # ReviewMark (DemaConsulting.ReviewMark from dotnet tool list) + reviewmark: + command: dotnet tool list + regex: '(?i)demaconsulting\.reviewmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' diff --git a/.yamllint.yaml b/.yamllint.yaml index d58cdd3..6c6c4fb 100644 --- a/.yamllint.yaml +++ b/.yamllint.yaml @@ -1,6 +1,15 @@ --- -# yamllint configuration for ReqStream -# This configuration defines the rules for YAML file linting +# YAML Linting Standards +# +# PURPOSE: +# - Maintain consistent code quality and readability standards +# - Support CI/CD workflows with reliable YAML parsing +# - Ensure professional documentation and configuration files +# +# DO NOT MODIFY: These rules represent coding standards +# - If files fail linting, fix the files to meet these standards +# - Do not relax rules to accommodate existing non-compliant files +# - Consistency across repositories is critical for maintainability extends: default @@ -17,7 +26,6 @@ rules: # Allow 'on:' in GitHub Actions workflows (not a boolean value) truthy: allowed-values: ['true', 'false', 'on', 'off'] - check-keys: true # Allow longer lines for URLs and complex expressions line-length: diff --git a/AGENTS.md b/AGENTS.md index 3f6c503..0f99426 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,6 +10,7 @@ written in YAML files. - **Software Developer** - Writes production code and self-validation tests in literate style - **Test Developer** - Creates unit and integration tests following AAA pattern - **Code Quality Agent** - Enforces linting, static analysis, and security standards +- **Code Review Agent** - Assists in performing formal file reviews - **Repo Consistency Agent** - Ensures downstream repositories remain consistent with template patterns ## Agent Selection Guide @@ -22,6 +23,7 @@ written in YAML files. - Add or update requirements → **Requirements Agent** - Ensure test coverage linkage in `requirements.yaml` → **Requirements Agent** - Run security scanning or address CodeQL alerts → **Code Quality Agent** +- Perform formal file reviews → **Code Review Agent** - Propagate template changes → **Repo Consistency Agent** ## Tech Stack diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 53b33d1..3b946e5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,49 +1,55 @@ # Contributing to ReqStream -Thank you for your interest in contributing to ReqStream! This document provides guidelines and instructions for -contributing to the project. +Thank you for your interest in contributing to ReqStream! We welcome contributions from the community and appreciate +your help in making this project better. ## Code of Conduct -This project adheres to the Contributor Covenant [Code of Conduct][code-of-conduct]. By participating, you are -expected to uphold this code. Please report unacceptable behavior through [GitHub Issues][issues] or by contacting -the project maintainers directly. +This project adheres to a [Code of Conduct][code-of-conduct]. By participating, you are expected to uphold this code. +Please report unacceptable behavior through GitHub. ## How to Contribute ### Reporting Bugs -If you find a bug, please create an issue using the bug report template. Include: +If you find a bug, please create an issue on GitHub with the following information: -- A clear description of the problem -- Steps to reproduce the issue -- Expected vs. actual behavior -- Version information (ReqStream version, .NET version, OS) -- Any relevant error messages or logs +- **Description**: Clear description of the bug +- **Steps to Reproduce**: Detailed steps to reproduce the issue +- **Expected Behavior**: What you expected to happen +- **Actual Behavior**: What actually happened +- **Environment**: Operating system, .NET version, ReqStream version +- **Logs**: Any relevant error messages or logs ### Suggesting Features -We welcome feature suggestions! Please create an issue using the feature request template. Include: +We welcome feature suggestions! Please create an issue on GitHub with: -- A clear description of the problem you're trying to solve -- Your proposed solution -- Any alternative solutions you've considered -- Examples or mockups if applicable +- **Feature Description**: Clear description of the proposed feature +- **Use Case**: Why this feature would be useful +- **Proposed Solution**: Your ideas on how to implement it (optional) +- **Alternatives**: Any alternative solutions you've considered (optional) -### Contributing Code +### Submitting Pull Requests -1. **Fork the repository** and create a branch for your changes -2. **Make your changes** following the coding standards below -3. **Test your changes** thoroughly -4. **Submit a pull request** with a clear description of your changes +We follow a standard GitHub workflow for contributions: + +1. **Fork** the repository +2. **Clone** your fork locally +3. **Create a branch** for your changes (`git checkout -b feature/my-feature`) +4. **Make your changes** following our coding standards +5. **Test your changes** thoroughly +6. **Commit your changes** with clear commit messages +7. **Push** to your fork +8. **Create a Pull Request** to the main repository ## Development Setup ### Prerequisites -- .NET SDK 8.0, 9.0, or 10.0 +- [.NET SDK][dotnet-download] 8.0, 9.0, or 10.0 - Git -- A code editor (Visual Studio, VS Code, JetBrains Rider, etc.) +- A code editor (Visual Studio, VS Code, or Rider recommended) ### Getting Started @@ -57,80 +63,90 @@ We welcome feature suggestions! Please create an issue using the feature request 2. Restore dependencies: ```bash + dotnet tool restore dotnet restore ``` -3. Build the solution: +3. Build the project: ```bash - dotnet build + dotnet build --configuration Release ``` -4. Run tests: +4. Run unit tests: ```bash - dotnet test + dotnet test --configuration Release ``` ## Coding Standards +### General Guidelines + +- Follow the [C# Coding Conventions][csharp-conventions] +- Use clear, descriptive names for variables, methods, and classes +- Write XML documentation comments for all public, internal, and private members +- Keep methods focused and single-purpose +- Write tests for new functionality + ### Code Style -This project follows the coding standards defined in `.editorconfig`. Key conventions: +This project enforces code style through `.editorconfig`. Key requirements: - **Indentation**: 4 spaces for C#, 2 spaces for YAML/JSON/XML -- **Line endings**: LF (Unix-style) +- **Line Endings**: LF (Unix-style) - **Encoding**: UTF-8 +- **Namespaces**: Use file-scoped namespace declarations - **Braces**: Required for all control statements -- **Naming**: - - Interfaces: `IRequirementParser` +- **Naming Conventions**: + - Interfaces: `IInterfaceName` - Classes/Structs/Enums: `PascalCase` - Methods/Properties: `PascalCase` - - Parameters/Local variables: `camelCase` - -### Documentation - -- Use XML documentation comments (`///`) for all public APIs -- Include meaningful comments for complex logic -- Keep README.md and other documentation up to date - -### Testing - -- All new features must include tests -- Tests should follow the AAA (Arrange, Act, Assert) pattern -- Test method naming: `TestMethod_Scenario_ExpectedBehavior` -- All unit tests must pass before submitting a PR -- Aim for high code coverage (>80%) + - Parameters/Local Variables: `camelCase` + +### XML Documentation + +All members require XML documentation with proper indentation: + +```csharp +/// +/// Brief description of what this does. +/// +/// Description of the parameter. +/// Description of the return value. +public int ExampleMethod(string parameter) +{ + // Implementation +} +``` -### Commit Messages +Note the spaces after `///` for proper indentation in summary blocks. -Write clear, descriptive commit messages: +## Testing Guidelines -- Use the imperative mood ("Add feature" not "Added feature") -- Keep the first line under 72 characters -- Add details in the body if needed +### Test Framework -Example: +We use MSTest v4 for unit and integration tests. -```text -Add validation for requirement IDs +### Test Naming Convention -- Ensures requirement IDs are unique -- Adds tests for duplicate ID detection -- Updates error messages for clarity -``` +Use the pattern: `ClassName_MethodUnderTest_Scenario_ExpectedBehavior` -## Quality Checks +Examples: -Before submitting a pull request, ensure your code passes all quality checks: +- `Program_Main_NoArguments_ReturnsSuccess` +- `Context_Create_WithInvalidFlag_ThrowsArgumentException` +- `Validation_Run_AllTests_ReturnsSuccess` -### Build and Test +### Writing Tests -```bash -dotnet restore -dotnet build --configuration Release -dotnet test --configuration Release -``` +- Write tests that are clear and focused +- Use modern MSTest v4 assertions: + - `Assert.HasCount(expectedCount, collection)` + - `Assert.IsEmpty(collection)` + - `Assert.DoesNotContain(item, collection)` +- Always clean up resources (use `try/finally` for console redirection) +- Link tests to requirements in `requirements.yaml` when applicable ### Running Tests @@ -155,26 +171,20 @@ dotnet run --project src/DemaConsulting.ReqStream \ --configuration Release --framework net10.0 --no-build -- --validate ``` -### Linting - -The CI pipeline runs the following checks: +## Documentation -- **Markdown linting**: Checks markdown file formatting -- **Spell checking**: Validates spelling in markdown and C# files -- **YAML linting**: Validates YAML file structure +### Markdown Guidelines -You can run these locally if you have the tools installed: - -```bash -# Markdown linting -markdownlint-cli2 "**/*.md" +All markdown files must follow these rules (enforced by markdownlint): -# Spell checking -cspell "**/*.md" "**/*.cs" - -# YAML linting -yamllint . -``` +- Maximum line length: 120 characters +- Use ATX-style headers (`# Header`) +- Lists must be surrounded by blank lines +- Use reference-style links: `[text][ref]` with `[ref]: url` at document end +- **Exceptions**: + - `README.md` uses absolute URLs (it's included in the NuGet package) + - AI agent markdown files (`.github/agents/*.agent.md`) use inline links + `[text](url)` so URLs are visible in agent context ### Spell Checking @@ -186,47 +196,102 @@ spell-checking failure. Doing so defeats the purpose of spell-checking and reduc correctly, raise a **proposal** (e.g. comment in a pull request) explaining why the word should be added. The proposal must be reviewed and approved before the word is added to the list. -## Pull Request Process +## Quality Checks + +Before submitting a pull request, ensure all quality checks pass: + +### 1. Build, Test, and Validate + +```bash +# Build the project +dotnet build --configuration Release -1. **Update documentation** if your changes affect usage or behavior -2. **Add tests** for new functionality or bug fixes -3. **Ensure all tests pass** and the code builds without warnings -4. **Update the README** if necessary -5. **Submit the PR** with a clear description of your changes -6. **Address review feedback** promptly - -### PR Guidelines - -- Keep PRs focused on a single feature or fix -- Write a clear PR description explaining what and why -- Reference any related issues -- Be responsive to review feedback -- Ensure CI checks pass - -## Project Structure - -```text -ReqStream/ -├── .github/ # GitHub configuration (workflows, issue templates) -├── src/ # Source code -│ └── DemaConsulting.ReqStream/ -├── test/ # Test projects -│ └── DemaConsulting.ReqStream.Tests/ -├── .editorconfig # Code style configuration -├── AGENTS.md # AI agent guidelines -├── CODE_OF_CONDUCT.md # Code of conduct -├── CONTRIBUTING.md # This file -├── LICENSE # MIT License -└── README.md # Project documentation +# Run unit tests +dotnet test --configuration Release + +# Run self-validation tests +dotnet run --project src/DemaConsulting.ReqStream --configuration Release --framework net10.0 --no-build -- --validate ``` -## Questions? +All tests must pass with zero warnings. + +### 2. Linting + +```bash +# Use the lint script which installs dependencies and runs all linters +./lint.sh # Linux/macOS (or: bash ./lint.sh) +cmd /c lint.bat # Windows (Command Prompt) +./lint.bat # Windows (PowerShell) +``` + +### 3. Code Coverage + +Maintain or improve code coverage. Use the `--collect "XPlat Code Coverage"` option when running tests. + +## Commit Messages + +Write clear, concise commit messages: + +- Use present tense ("Add feature" not "Added feature") +- Use imperative mood ("Move cursor to..." not "Moves cursor to...") +- Limit first line to 72 characters +- Reference issues and pull requests when applicable + +Examples: + +- `Add support for custom report headers` +- `Fix crash when results file path is invalid` +- `Update documentation for --report-depth option` +- `Refactor argument parsing for better testability` + +## Pull Request Process + +1. **Update Documentation**: Update relevant documentation for your changes +2. **Add Tests**: Include tests that cover your changes +3. **Run Quality Checks**: Ensure all linters, tests, and builds pass +4. **Submit PR**: Create a pull request with a clear description +5. **Code Review**: Address feedback from maintainers +6. **Merge**: Once approved, a maintainer will merge your PR + +### Pull Request Template + +When creating a pull request, include: + +- **Description**: What changes does this PR introduce? +- **Motivation**: Why are these changes needed? +- **Related Issues**: Link to any related issues +- **Testing**: How have you tested these changes? +- **Checklist**: + - [ ] Tests added/updated + - [ ] Documentation updated + - [ ] All tests pass + - [ ] Code follows style guidelines + - [ ] No new warnings introduced + +## Requirements Management + +ReqStream uses itself for requirements traceability: + +- All requirements are defined in `requirements.yaml` +- Each requirement should be linked to test cases +- Run `dotnet reqstream` to generate requirements documentation +- Use the `--enforce` flag to ensure all requirements have test coverage + +## Release Process + +Releases are managed by project maintainers. The process includes: + +1. Version bump in project files +2. Tag the release in Git +3. Build and test across all supported platforms +4. Publish NuGet package +5. Create GitHub release with artifacts and release notes -If you have questions about contributing, feel free to: +## Getting Help -- Open an issue for discussion -- Reach out to the maintainers -- Check the [AGENTS.md][agents] file for detailed technical guidelines +- **Questions**: Use [GitHub Discussions][discussions] +- **Bugs**: Report via [GitHub Issues][issues] +- **Security**: See [SECURITY.md][security] for vulnerability reporting ## License @@ -234,6 +299,9 @@ By contributing to ReqStream, you agree that your contributions will be licensed Thank you for contributing to ReqStream! -[code-of-conduct]: CODE_OF_CONDUCT.md -[agents]: AGENTS.md +[code-of-conduct]: https://github.com/demaconsulting/ReqStream/blob/main/CODE_OF_CONDUCT.md +[dotnet-download]: https://dotnet.microsoft.com/download +[csharp-conventions]: https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions +[discussions]: https://github.com/demaconsulting/ReqStream/discussions [issues]: https://github.com/demaconsulting/ReqStream/issues +[security]: https://github.com/demaconsulting/ReqStream/blob/main/SECURITY.md diff --git a/lint.bat b/lint.bat index 6c22bdc..f94b53d 100644 --- a/lint.bat +++ b/lint.bat @@ -1,20 +1,40 @@ @echo off -REM Run all linters for ReqStream (Windows) +setlocal -echo Checking markdown... -call npx markdownlint-cli2 "**/*.md" -if %errorlevel% neq 0 exit /b %errorlevel% +REM Comprehensive Linting Script +REM +REM PURPOSE: +REM - Run ALL lint checks when executed (no options or modes) +REM - Output lint failures directly for agent parsing +REM - NO command-line arguments, pretty printing, or colorization +REM - Agents execute this script to identify files needing fixes + +set "LINT_ERROR=0" + +REM Install npm dependencies +call npm install -echo Checking spelling... -call npx cspell "**/*.{cs,md,json,yaml,yml}" --no-progress -if %errorlevel% neq 0 exit /b %errorlevel% +REM Create Python virtual environment (for yamllint) if missing +if not exist ".venv\Scripts\activate.bat" ( + python -m venv .venv +) +call .venv\Scripts\activate.bat +pip install -r pip-requirements.txt + +REM Run spell check +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 +call npx markdownlint-cli2 "**/*.md" +if errorlevel 1 set "LINT_ERROR=1" -echo Checking YAML... -call yamllint -c .yamllint.yaml . -if %errorlevel% neq 0 exit /b %errorlevel% +REM Run yamllint check +yamllint . +if errorlevel 1 set "LINT_ERROR=1" -echo Checking code formatting... +REM Run .NET formatting check (verifies no changes are needed) dotnet format --verify-no-changes -if %errorlevel% neq 0 exit /b %errorlevel% +if errorlevel 1 set "LINT_ERROR=1" -echo All linting passed! +exit /b %LINT_ERROR% diff --git a/lint.sh b/lint.sh index 59ab732..7d8116b 100755 --- a/lint.sh +++ b/lint.sh @@ -1,18 +1,35 @@ -#!/usr/bin/env bash -# Run all linters for ReqStream +#!/bin/bash -set -e # Exit on error +# Comprehensive Linting Script +# +# PURPOSE: +# - Run ALL lint checks when executed (no options or modes) +# - Output lint failures directly for agent parsing +# - NO command-line arguments, pretty printing, or colorization +# - Agents execute this script to identify files needing fixes -echo "📝 Checking markdown..." -npx markdownlint-cli2 "**/*.md" +lint_error=0 -echo "🔤 Checking spelling..." -npx cspell "**/*.{cs,md,json,yaml,yml}" --no-progress +# Install npm dependencies +npm install -echo "📋 Checking YAML..." -yamllint -c .yamllint.yaml . +# Create Python virtual environment (for yamllint) +if [ ! -d ".venv" ]; then + python -m venv .venv +fi +source .venv/bin/activate +pip install -r pip-requirements.txt -echo "🎨 Checking code formatting..." -dotnet format --verify-no-changes +# Run spell check +npx cspell --no-progress --no-color "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" || lint_error=1 -echo "✨ All linting passed!" +# Run markdownlint check +npx markdownlint-cli2 "**/*.md" || lint_error=1 + +# Run yamllint check +yamllint . || lint_error=1 + +# Run .NET formatting check (verifies no changes are needed) +dotnet format --verify-no-changes || lint_error=1 + +exit $lint_error diff --git a/package.json b/package.json index 9487fa5..a57dc1f 100644 --- a/package.json +++ b/package.json @@ -2,6 +2,8 @@ "private": true, "devDependencies": { "@mermaid-js/mermaid-cli": "11.12.0", + "cspell": "9.7.0", + "markdownlint-cli2": "0.21.0", "mermaid-filter": "1.4.7" } } diff --git a/pip-requirements.txt b/pip-requirements.txt new file mode 100644 index 0000000..7ce0eab --- /dev/null +++ b/pip-requirements.txt @@ -0,0 +1 @@ +yamllint==1.38.0 From 0194ff155363007a3f4101fd8020dace8cc01360 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 02:12:02 +0000 Subject: [PATCH 06/10] Split requirements.yaml into per-unit files and update .reviewmark.yaml review sets Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> Agent-Logs-Url: https://github.com/demaconsulting/ReqStream/sessions/e078de59-4efb-45e9-98e2-182adb75849f --- .reviewmark.yaml | 21 + docs/reqstream/ots-buildmark.yaml | 16 + docs/reqstream/ots-mstest.yaml | 23 + docs/reqstream/ots-reqstream.yaml | 17 + docs/reqstream/ots-sarifmark.yaml | 17 + docs/reqstream/ots-sonarmark.yaml | 19 + docs/reqstream/ots-versionmark.yaml | 17 + docs/reqstream/platform-requirements.yaml | 88 +++ docs/reqstream/unit-context.yaml | 84 +++ docs/reqstream/unit-program.yaml | 4 + docs/reqstream/unit-requirements.yaml | 124 +++++ docs/reqstream/unit-trace-matrix.yaml | 211 ++++++++ docs/reqstream/unit-validation.yaml | 33 ++ requirements.yaml | 621 +--------------------- 14 files changed, 687 insertions(+), 608 deletions(-) create mode 100644 docs/reqstream/ots-buildmark.yaml create mode 100644 docs/reqstream/ots-mstest.yaml create mode 100644 docs/reqstream/ots-reqstream.yaml create mode 100644 docs/reqstream/ots-sarifmark.yaml create mode 100644 docs/reqstream/ots-sonarmark.yaml create mode 100644 docs/reqstream/ots-versionmark.yaml create mode 100644 docs/reqstream/platform-requirements.yaml create mode 100644 docs/reqstream/unit-context.yaml create mode 100644 docs/reqstream/unit-program.yaml create mode 100644 docs/reqstream/unit-requirements.yaml create mode 100644 docs/reqstream/unit-trace-matrix.yaml create mode 100644 docs/reqstream/unit-validation.yaml diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 8bf2eda..8a8dcd4 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -27,23 +27,27 @@ reviews: - id: ReqStream-Context title: Review of ReqStream Context Unit paths: + - "docs/reqstream/unit-context.yaml" - "src/**/Context.cs" - "test/**/ContextTests.cs" - id: ReqStream-Program title: Review of ReqStream Program Unit paths: + - "docs/reqstream/unit-program.yaml" - "src/**/Program.cs" - "test/**/ProgramTests.cs" - id: ReqStream-Validation title: Review of ReqStream Validation Unit paths: + - "docs/reqstream/unit-validation.yaml" - "src/**/Validation.cs" - id: ReqStream-Requirements title: Review of ReqStream Requirements Unit paths: + - "docs/reqstream/unit-requirements.yaml" - "src/**/Requirement.cs" - "src/**/Requirements.cs" - "src/**/Section.cs" @@ -53,7 +57,24 @@ reviews: - id: ReqStream-TraceMatrix title: Review of ReqStream TraceMatrix Unit paths: + - "docs/reqstream/unit-trace-matrix.yaml" - "src/**/TraceMatrix.cs" - "test/**/TraceMatrixTests.cs" - "test/**/TraceMatrixReadTests.cs" - "test/**/TraceMatrixExportTests.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" diff --git a/docs/reqstream/ots-buildmark.yaml b/docs/reqstream/ots-buildmark.yaml new file mode 100644 index 0000000..980e0e2 --- /dev/null +++ b/docs/reqstream/ots-buildmark.yaml @@ -0,0 +1,16 @@ +--- +sections: + - title: ReqStream Requirements + sections: + - title: OTS Software + requirements: + - id: ReqStream-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..3fafcf4 --- /dev/null +++ b/docs/reqstream/ots-mstest.yaml @@ -0,0 +1,23 @@ +--- +sections: + - title: ReqStream Requirements + sections: + - title: OTS Software + requirements: + - id: ReqStream-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_SetsVersionProperty + - Context_Create_HelpFlags_SetsHelpProperty + - Context_Create_ValidateFlag_SetsValidateProperty + - Context_Create_EnforceFlag_SetsEnforceProperty + - Requirements_Read_SimpleRequirement_ParsesCorrectly + - Program_Run_WithVersionFlag_PrintsVersion + - Program_Run_WithHelpFlag_PrintsHelp diff --git a/docs/reqstream/ots-reqstream.yaml b/docs/reqstream/ots-reqstream.yaml new file mode 100644 index 0000000..1d38613 --- /dev/null +++ b/docs/reqstream/ots-reqstream.yaml @@ -0,0 +1,17 @@ +--- +sections: + - title: ReqStream Requirements + sections: + - title: OTS Software + requirements: + - id: ReqStream-OTS-ReqStream + title: ReqStream shall enforce that every requirement is linked to passing test evidence. + justification: | + DemaConsulting.ReqStream processes requirements.yaml and the TRX test-result files to + produce a requirements report, justifications document, and traceability matrix. When + run with --enforce, it exits with a non-zero code if any requirement lacks test evidence, + making unproven requirements a build-breaking condition. A successful pipeline run with + --enforce proves all requirements are covered and that ReqStream is functioning. + tags: [ots] + tests: + - ReqStream_EnforcementMode diff --git a/docs/reqstream/ots-sarifmark.yaml b/docs/reqstream/ots-sarifmark.yaml new file mode 100644 index 0000000..2c7cbdf --- /dev/null +++ b/docs/reqstream/ots-sarifmark.yaml @@ -0,0 +1,17 @@ +--- +sections: + - title: ReqStream Requirements + sections: + - title: OTS Software + requirements: + - id: ReqStream-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..6be16ed --- /dev/null +++ b/docs/reqstream/ots-sonarmark.yaml @@ -0,0 +1,19 @@ +--- +sections: + - title: ReqStream Requirements + sections: + - title: OTS Software + requirements: + - id: ReqStream-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..1fadfeb --- /dev/null +++ b/docs/reqstream/ots-versionmark.yaml @@ -0,0 +1,17 @@ +--- +sections: + - title: ReqStream Requirements + sections: + - title: OTS Software + requirements: + - id: ReqStream-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..593294c --- /dev/null +++ b/docs/reqstream/platform-requirements.yaml @@ -0,0 +1,88 @@ +--- +sections: + - title: ReqStream Requirements + sections: + - title: Platform Support + requirements: + - id: ReqStream-Plt-Windows + title: The tool shall run on Windows operating systems. + justification: | + Windows support is essential for .NET developers who primarily work in Windows environments + and use Visual Studio. + tags: + - platform + tests: + - "windows@ReqStream_RequirementsProcessing" + - "windows@ReqStream_TraceMatrix" + - "windows@ReqStream_ReportExport" + - "windows@ReqStream_TagsFiltering" + - "windows@ReqStream_EnforcementMode" + + - id: ReqStream-Plt-Linux + title: The tool shall run on Linux operating systems. + justification: | + Linux support enables use in containerized CI/CD environments and cloud-based build systems + that typically use Linux. + tags: + - platform + tests: + - "ubuntu@ReqStream_RequirementsProcessing" + - "ubuntu@ReqStream_TraceMatrix" + - "ubuntu@ReqStream_ReportExport" + - "ubuntu@ReqStream_TagsFiltering" + - "ubuntu@ReqStream_EnforcementMode" + + - id: ReqStream-Plt-MacOS + title: The tool shall run on macOS operating systems. + justification: | + macOS support is essential for developers using Apple platforms who need to run + ReqStream locally and in CI/CD pipelines on macOS agents. + tags: + - platform + tests: + - "macos@ReqStream_RequirementsProcessing" + - "macos@ReqStream_TraceMatrix" + - "macos@ReqStream_ReportExport" + - "macos@ReqStream_TagsFiltering" + - "macos@ReqStream_EnforcementMode" + + - id: ReqStream-Plt-Net8 + title: The tool shall support .NET 8.0 runtime. + justification: | + .NET 8.0 is an LTS release, providing long-term stability and support for enterprise users. + tags: + - platform + tests: + - "dotnet8.x@ReqStream_RequirementsProcessing" + - "dotnet8.x@ReqStream_TraceMatrix" + - "dotnet8.x@ReqStream_ReportExport" + - "dotnet8.x@ReqStream_TagsFiltering" + - "dotnet8.x@ReqStream_EnforcementMode" + + - id: ReqStream-Plt-Net9 + title: The tool shall support .NET 9.0 runtime. + justification: | + .NET 9.0 support enables users to leverage the latest .NET features and performance + improvements. + tags: + - platform + tests: + - "dotnet9.x@ReqStream_RequirementsProcessing" + - "dotnet9.x@ReqStream_TraceMatrix" + - "dotnet9.x@ReqStream_ReportExport" + - "dotnet9.x@ReqStream_TagsFiltering" + - "dotnet9.x@ReqStream_EnforcementMode" + + - id: ReqStream-Plt-Net10 + title: The tool shall support .NET 10.0 runtime. + justification: | + .NET 10.0 support ensures the tool remains compatible with the latest .NET ecosystem and + future-proofs the project. + tags: + - platform + tests: + - "dotnet10.x@ReqStream_RequirementsProcessing" + - "dotnet10.x@ReqStream_TraceMatrix" + - "dotnet10.x@ReqStream_ReportExport" + - "dotnet10.x@ReqStream_TagsFiltering" + - "dotnet10.x@ReqStream_EnforcementMode" diff --git a/docs/reqstream/unit-context.yaml b/docs/reqstream/unit-context.yaml new file mode 100644 index 0000000..7750180 --- /dev/null +++ b/docs/reqstream/unit-context.yaml @@ -0,0 +1,84 @@ +--- +sections: + - title: ReqStream Requirements + sections: + - title: Command-Line Interface + requirements: + - id: ReqStream-Cmd-Cli + title: The tool shall provide a command-line interface. + justification: | + A CLI interface enables automation in CI/CD pipelines and allows integration with scripts + and build processes. This is essential for the tool's primary use case. + tags: + - cli + tests: + - Context_Create_NoArguments_ReturnsDefaultContext + - Context_Create_MultipleArguments_ParsesAllCorrectly + + - id: ReqStream-Cmd-Version + title: The tool shall display version information when requested. + justification: | + Version information is critical for debugging, support, and ensuring compatibility with + documentation and scripts. + tags: + - cli + tests: + - Program_Run_WithVersionFlag_PrintsVersion + - Context_Create_VersionFlag_SetsVersionProperty + + - id: ReqStream-Cmd-Help + title: The tool shall display help information when requested. + justification: | + Help information improves user experience and reduces the learning curve for new users by + providing quick access to command-line options. + tags: + - cli + tests: + - Program_Run_WithHelpFlag_PrintsHelp + - Context_Create_HelpFlags_SetsHelpProperty + + - id: ReqStream-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. + tags: + - cli + tests: + - Context_WriteError_NormalMode_WritesToConsole + + - id: ReqStream-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. + tags: + - cli + tests: + - Context_Create_UnsupportedArgument_ThrowsException + - Context_Create_MissingLogFilename_ThrowsException + - Context_Create_MissingResultsFilename_ThrowsException + + - id: ReqStream-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. + tags: + - cli + tests: + - Context_WriteError_NormalMode_WritesToConsole + + - title: Logging + requirements: + - id: ReqStream-Log-FileOutput + title: The tool shall support writing output to a log file. + justification: | + Log file support enables capturing tool output for debugging, audit trails, and CI/CD + integration where console output may be ephemeral. + tags: + - logging + tests: + - Context_Create_WithLogFile_WritesToLogFile + - Context_Create_WithLogFileAndSilent_WritesToLogOnly + - Context_Dispose_WithLogFile_ClosesLogFile diff --git a/docs/reqstream/unit-program.yaml b/docs/reqstream/unit-program.yaml new file mode 100644 index 0000000..dd2fc55 --- /dev/null +++ b/docs/reqstream/unit-program.yaml @@ -0,0 +1,4 @@ +--- +sections: + - title: ReqStream Requirements + sections: [] diff --git a/docs/reqstream/unit-requirements.yaml b/docs/reqstream/unit-requirements.yaml new file mode 100644 index 0000000..1aeb0aa --- /dev/null +++ b/docs/reqstream/unit-requirements.yaml @@ -0,0 +1,124 @@ +--- +sections: + - title: ReqStream Requirements + sections: + - title: Requirements File Processing + requirements: + - id: ReqStream-Req-YamlProcessing + title: The tool shall process YAML requirements files. + justification: | + YAML provides a human-readable, version-control-friendly format for managing requirements. + This makes requirements accessible to both technical and non-technical stakeholders. + tags: + - requirements + tests: + - Requirements_Read_SimpleRequirement_ParsesCorrectly + - Program_Run_WithRequirementsFiles_ProcessesSuccessfully + - Requirements_Read_ComplexStructure_ParsesCorrectly + + - id: ReqStream-Req-GlobPatterns + title: The tool shall support glob patterns for requirements files. + justification: | + Glob patterns enable flexible file selection and reduce the need for explicit file listing, + making the tool easier to use in various project structures. + tags: + - requirements + tests: + - Context_Create_WithRequirementsPattern_ExpandsGlobPattern + + - id: ReqStream-Req-Validation + title: The tool shall validate requirements file structure. + justification: | + Early validation prevents runtime errors and ensures requirements data integrity, catching + issues before they impact downstream processes. + tags: + - requirements + tests: + - Requirements_Read_BlankSectionTitle_ThrowsExceptionWithFileLocation + - Requirements_Read_BlankRequirementId_ThrowsExceptionWithFileLocation + - Requirements_Read_BlankRequirementTitle_ThrowsExceptionWithFileLocation + - Requirements_Read_DuplicateRequirementId_ThrowsException + - Requirements_Read_DuplicateRequirementId_ExceptionIncludesFileLocation + + - id: ReqStream-Req-Hierarchy + title: The tool shall support hierarchical sections and subsections. + justification: | + Hierarchical organization allows requirements to be grouped logically by system components, + features, or concerns, improving maintainability and navigation. + tags: + - requirements + tests: + - Requirements_Read_NestedSections_ParsesHierarchyCorrectly + - Requirements_Export_NestedSections_CreatesHierarchy + + - id: ReqStream-Req-Includes + title: The tool shall support file includes in requirements files. + justification: | + File includes enable modular requirements management, allowing teams to organize requirements + across multiple files and reducing merge conflicts in version control. + tags: + - requirements + tests: + - Requirements_Read_WithIncludes_MergesFilesCorrectly + - Requirements_Read_MultipleFiles_MergesAllFiles + - Requirements_Read_IncludeLoop_DoesNotCauseInfiniteLoop + + - id: ReqStream-Req-SectionMerging + title: The tool shall merge sections with the same hierarchy path. + justification: | + Section merging allows multiple files to contribute to the same logical section, supporting + distributed authoring and modular organization of requirements. + tags: + - requirements + tests: + - Requirements_Read_IdenticalSections_MergesCorrectly + - Requirements_Read_MultipleFilesWithSameSections_MergesSections + + - title: Requirements Definition + requirements: + - id: ReqStream-Req-UniqueIds + title: The tool shall require each requirement to have a unique identifier. + justification: | + Unique identifiers enable unambiguous referencing of requirements in documentation, test + mappings, and traceability reports. + tags: + - requirements + tests: + - Requirements_Read_DuplicateRequirementId_ThrowsException + - Requirements_Read_BlankRequirementId_ThrowsExceptionWithFileLocation + - Requirements_Read_MultipleFilesWithDuplicateIds_ThrowsException + + - id: ReqStream-Req-RequiredTitle + title: The tool shall require each requirement to have a title. + justification: | + Titles provide human-readable descriptions of requirements, making them understandable to + stakeholders without needing to reference external documentation. + tags: + - requirements + tests: + - Requirements_Read_BlankRequirementTitle_ThrowsExceptionWithFileLocation + + - id: ReqStream-Req-ParentChild + title: The tool shall support parent-child relationships between requirements. + justification: | + Parent-child relationships enable hierarchical requirement decomposition, allowing high-level + requirements to be satisfied through lower-level requirements. + tags: + - requirements + tests: + - Requirements_Read_RequirementWithChildren_ParsesChildrenCorrectly + - TraceMatrix_Export_WithChildRequirements_ConsidersChildTests + + - id: ReqStream-Req-TestMappings + title: The tool shall support test mappings for requirements. + justification: | + Test mappings establish traceability between requirements and tests, enabling verification + that requirements are adequately tested and satisfied. + tags: + - requirements + tests: + - Requirements_Read_RequirementWithTests_ParsesTestsCorrectly + - Requirements_Read_BlankTestNameInRequirement_ThrowsExceptionWithFileLocation + - Requirements_Read_TestMappings_AppliesMappingsCorrectly + - Requirements_Read_BlankTestNameInMapping_ThrowsExceptionWithFileLocation + - Requirements_Read_BlankMappingId_ThrowsExceptionWithFileLocation diff --git a/docs/reqstream/unit-trace-matrix.yaml b/docs/reqstream/unit-trace-matrix.yaml new file mode 100644 index 0000000..b14eb5d --- /dev/null +++ b/docs/reqstream/unit-trace-matrix.yaml @@ -0,0 +1,211 @@ +--- +sections: + - title: ReqStream Requirements + sections: + - title: Test Integration + requirements: + - id: ReqStream-Test-ResultFiles + title: The tool shall support processing test result files. + justification: | + Processing test results enables automated verification of requirement satisfaction and + integration with existing test infrastructure. + tags: + - testing + tests: + - TraceMatrix_WithNoFiles_CreatesEmptyMatrix + - TraceMatrix_MissingFile_ThrowsFileNotFoundException + - TraceMatrix_WithMultipleFiles_AggregatesResults + + - id: ReqStream-Test-TrxFormat + title: The tool shall support TRX format test results. + justification: | + TRX is the native test result format for .NET testing frameworks, enabling seamless + integration with .NET projects. + tags: + - testing + tests: + - TraceMatrix_WithTrxFile_ParsesCorrectly + - TraceMatrix_WithFailedTests_TracksFailures + + - id: ReqStream-Test-JUnitFormat + title: The tool shall support JUnit format test results. + justification: | + JUnit format is widely used across multiple programming ecosystems, enabling cross-platform + test result integration. + tags: + - testing + tests: + - TraceMatrix_WithJUnitFile_ParsesCorrectly + - TraceMatrix_WithJUnitFailedTests_TracksFailures + + - id: ReqStream-Test-GlobPatterns + title: The tool shall support glob patterns for test result files. + justification: | + Glob patterns simplify specification of multiple test result files and enable flexible + file selection across different test runs and platforms. + tags: + - testing + tests: + - Context_Create_WithTestsPattern_ExpandsGlobPattern + - TraceMatrix_WithMixedFormats_ProcessesBoth + + - id: ReqStream-Test-SourceFiltering + title: The tool shall support source-specific test matching using filepart@testname pattern. + justification: | + Source-specific matching enables requirements to reference tests from specific test runs + or platforms, supporting platform-specific requirements validation. + tags: + - testing + tests: + - TraceMatrix_WithSourceSpecificTests_MatchesCorrectly + - TraceMatrix_WithSourceSpecificTests_DoesNotMatchOtherSources + - TraceMatrix_WithMultipleSourceSpecifiers_MatchesAllRequirements + + - id: ReqStream-Test-CaseInsensitive + title: >- + The tool shall perform case-insensitive matching of file parts in source-specific + test names. + justification: | + Case-insensitive matching reduces errors and improves usability by allowing flexible + specification of file part identifiers. + tags: + - testing + tests: + - TraceMatrix_WithSourceSpecificTests_IsCaseInsensitive + + - id: ReqStream-Test-PartialFilenames + title: The tool shall support partial filename matching for source-specific tests. + justification: | + Partial matching simplifies test specification by allowing short, memorable identifiers + rather than requiring full filename matches. + tags: + - testing + tests: + - TraceMatrix_WithSourceSpecificTests_MatchesPartialFilename + + - id: ReqStream-Test-PlainTestNames + title: The tool shall support plain test names that aggregate from all sources. + justification: | + Plain test names enable requirements to aggregate test results across all platforms and + test runs without specifying each source explicitly. + tags: + - testing + tests: + - TraceMatrix_WithPlainTestNames_MatchesAllSources + + - id: ReqStream-Test-MixedTestNames + title: >- + The tool shall support mixing plain and source-specific test names in the same + requirement. + justification: | + Mixing test name types provides flexibility for requirements that need both platform-specific + and cross-platform test coverage. + tags: + - testing + tests: + - TraceMatrix_WithMixedTestNames_MatchesAppropriately + + - id: ReqStream-Test-MultipleRequirements + title: >- + The tool shall match tests to multiple requirements with mixed filter + references. + justification: | + Supporting multiple requirements with mixed references enables efficient test reuse and + accurate traceability across different requirement types. + tags: + - testing + tests: + - TraceMatrix_WithMixedFilterAndPlainReferences_MatchesBoth + + - title: Reporting + requirements: + - id: ReqStream-Rpt-MarkdownExport + title: The tool shall export requirements to markdown format. + justification: | + Markdown export enables requirements to be included in documentation, wikis, and other + human-readable formats for stakeholder communication. + tags: + - reporting + tests: + - Program_Run_WithRequirementsExport_GeneratesReport + - Requirements_Export_SimpleRequirements_CreatesMarkdownFile + - Requirements_Export_MultipleSections_ExportsAll + - Requirements_Export_EmptyRequirements_CreatesEmptyFile + + - id: ReqStream-Rpt-HeaderDepth + title: The tool shall support configurable markdown header depth for requirements reports. + justification: | + Configurable header depth allows requirements reports to be embedded in larger documents + while maintaining proper document structure. + tags: + - reporting + tests: + - Context_Create_ReportDepth_SetsReportDepthProperty + - Requirements_Export_WithCustomDepth_UsesCorrectHeaderLevel + + - id: ReqStream-Rpt-TraceMatrix + title: The tool shall export trace matrices to markdown format. + justification: | + Trace matrix export provides visibility into test coverage and requirement satisfaction, + essential for quality assurance and compliance. + tags: + - reporting + tests: + - Program_Run_WithTraceMatrixExport_GeneratesMatrix + - TraceMatrix_Export_SimpleTraceMatrix_CreatesMarkdownFile + - TraceMatrix_Export_WithFailedTests_ShowsFailures + - TraceMatrix_Export_WithNoTests_ShowsNotSatisfied + - TraceMatrix_Export_WithNotExecutedTests_ShowsNotExecuted + + - id: ReqStream-Rpt-TraceMatrixDepth + title: The tool shall support configurable markdown header depth for trace matrices. + justification: | + Configurable header depth allows trace matrices to be embedded in larger documents while + maintaining proper document structure. + tags: + - reporting + tests: + - Context_Create_MatrixDepth_SetsMatrixDepthProperty + - Requirements_Export_WithCustomDepth_UsesCorrectHeaderLevel + + - id: ReqStream-Rpt-TagFiltering + title: The tool shall support filtering requirements by tags. + justification: | + Tag-based filtering enables selective export of requirement subsets for focused reports, + security audits, compliance documentation, and targeted reviews. + tags: + - reporting + tests: + - Context_Create_FilterArgument_ParsesTagsCorrectly + - Context_Create_FilterArgumentWithSpaces_TrimsAndParsesTagsCorrectly + - Context_Create_FilterSingleTag_ParsesCorrectly + - Requirements_Export_WithFilterTags_ExportsOnlyMatchingRequirements + - Requirements_Export_WithMultipleFilterTags_ExportsRequirementsMatchingAnyTag + - Requirements_ExportJustifications_WithFilterTags_ExportsOnlyMatchingRequirements + - TraceMatrix_Export_WithFilterTags_ExportsOnlyMatchingRequirements + - TraceMatrix_CalculateSatisfiedRequirements_WithFilterTags_CountsOnlyMatchingRequirements + - TraceMatrix_GetUnsatisfiedRequirements_WithFilterTags_ReturnsOnlyMatchingRequirements + + - id: ReqStream-Rpt-Justifications + title: The tool shall export requirement justifications to markdown format. + justification: | + Justification export enables stakeholders to understand the rationale behind + requirements, supporting design reviews, audits, and compliance activities. + tags: + - reporting + tests: + - Requirements_ExportJustifications_WithJustifications_CreatesMarkdownFile + - Requirements_ExportJustifications_WithoutJustifications_CreatesHeadersOnly + - Requirements_ExportJustifications_NestedSections_CreatesHierarchy + + - id: ReqStream-Rpt-JustificationsDepth + title: >- + The tool shall support configurable markdown header depth for justification + reports. + justification: | + Configurable header depth allows justification reports to be embedded in larger + documents while maintaining proper document structure. + tags: + - reporting + tests: + - Requirements_ExportJustifications_WithCustomDepth_UsesCorrectHeaderLevel diff --git a/docs/reqstream/unit-validation.yaml b/docs/reqstream/unit-validation.yaml new file mode 100644 index 0000000..db5d759 --- /dev/null +++ b/docs/reqstream/unit-validation.yaml @@ -0,0 +1,33 @@ +--- +sections: + - title: ReqStream Requirements + sections: + - title: Validation + requirements: + - id: ReqStream-Val-SelfValidation + title: The tool shall support self-validation mode. + justification: | + Self-validation ensures the tool's own integrity and serves as a smoke test for + installation and configuration issues. + tags: + - validation + tests: + - Program_Run_WithValidateFlag_RunsValidation + - Context_Create_ValidateFlag_SetsValidateProperty + + - id: ReqStream-Val-EnforcementMode + title: >- + The tool shall support enforcement mode to fail when requirements are + not fully tested. + justification: | + Enforcement mode enables CI/CD pipelines to block releases when requirements + lack test coverage, ensuring product quality and compliance. + tags: + - validation + tests: + - Context_Create_EnforceFlag_SetsEnforceProperty + - Program_Run_WithEnforcementAndFullySatisfiedRequirements_Succeeds + - Program_Run_WithEnforcementAndUnsatisfiedRequirements_Fails + - Program_Run_WithEnforcementAndNoTests_Fails + - Program_Run_WithEnforcementAndFailedTests_Fails + - ReqStream_EnforcementMode diff --git a/requirements.yaml b/requirements.yaml index a05d146..42516f2 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -28,611 +28,16 @@ # dotnet10.x@TestName - proves the self-validation test ran with .NET 10.x runtime # --- -sections: - - title: ReqStream Requirements - sections: - - title: Command-Line Interface - requirements: - - id: ReqStream-Cmd-Cli - title: The tool shall provide a command-line interface. - justification: | - A CLI interface enables automation in CI/CD pipelines and allows integration with scripts - and build processes. This is essential for the tool's primary use case. - tags: - - cli - tests: - - Context_Create_NoArguments_ReturnsDefaultContext - - Context_Create_MultipleArguments_ParsesAllCorrectly - - - id: ReqStream-Cmd-Version - title: The tool shall display version information when requested. - justification: | - Version information is critical for debugging, support, and ensuring compatibility with - documentation and scripts. - tags: - - cli - tests: - - Program_Run_WithVersionFlag_PrintsVersion - - Context_Create_VersionFlag_SetsVersionProperty - - - id: ReqStream-Cmd-Help - title: The tool shall display help information when requested. - justification: | - Help information improves user experience and reduces the learning curve for new users by - providing quick access to command-line options. - tags: - - cli - tests: - - Program_Run_WithHelpFlag_PrintsHelp - - Context_Create_HelpFlags_SetsHelpProperty - - - id: ReqStream-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. - tags: - - cli - tests: - - Context_WriteError_NormalMode_WritesToConsole - - - id: ReqStream-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. - tags: - - cli - tests: - - Context_Create_UnsupportedArgument_ThrowsException - - Context_Create_MissingLogFilename_ThrowsException - - Context_Create_MissingResultsFilename_ThrowsException - - - id: ReqStream-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. - tags: - - cli - tests: - - Context_WriteError_NormalMode_WritesToConsole - - - title: Requirements File Processing - requirements: - - id: ReqStream-Req-YamlProcessing - title: The tool shall process YAML requirements files. - justification: | - YAML provides a human-readable, version-control-friendly format for managing requirements. - This makes requirements accessible to both technical and non-technical stakeholders. - tags: - - requirements - tests: - - Requirements_Read_SimpleRequirement_ParsesCorrectly - - Program_Run_WithRequirementsFiles_ProcessesSuccessfully - - Requirements_Read_ComplexStructure_ParsesCorrectly - - - id: ReqStream-Req-GlobPatterns - title: The tool shall support glob patterns for requirements files. - justification: | - Glob patterns enable flexible file selection and reduce the need for explicit file listing, - making the tool easier to use in various project structures. - tags: - - requirements - tests: - - Context_Create_WithRequirementsPattern_ExpandsGlobPattern - - - id: ReqStream-Req-Validation - title: The tool shall validate requirements file structure. - justification: | - Early validation prevents runtime errors and ensures requirements data integrity, catching - issues before they impact downstream processes. - tags: - - requirements - tests: - - Requirements_Read_BlankSectionTitle_ThrowsExceptionWithFileLocation - - Requirements_Read_BlankRequirementId_ThrowsExceptionWithFileLocation - - Requirements_Read_BlankRequirementTitle_ThrowsExceptionWithFileLocation - - Requirements_Read_DuplicateRequirementId_ThrowsException - - Requirements_Read_DuplicateRequirementId_ExceptionIncludesFileLocation - - - id: ReqStream-Req-Hierarchy - title: The tool shall support hierarchical sections and subsections. - justification: | - Hierarchical organization allows requirements to be grouped logically by system components, - features, or concerns, improving maintainability and navigation. - tags: - - requirements - tests: - - Requirements_Read_NestedSections_ParsesHierarchyCorrectly - - Requirements_Export_NestedSections_CreatesHierarchy - - - id: ReqStream-Req-Includes - title: The tool shall support file includes in requirements files. - justification: | - File includes enable modular requirements management, allowing teams to organize requirements - across multiple files and reducing merge conflicts in version control. - tags: - - requirements - tests: - - Requirements_Read_WithIncludes_MergesFilesCorrectly - - Requirements_Read_MultipleFiles_MergesAllFiles - - Requirements_Read_IncludeLoop_DoesNotCauseInfiniteLoop - - - id: ReqStream-Req-SectionMerging - title: The tool shall merge sections with the same hierarchy path. - justification: | - Section merging allows multiple files to contribute to the same logical section, supporting - distributed authoring and modular organization of requirements. - tags: - - requirements - tests: - - Requirements_Read_IdenticalSections_MergesCorrectly - - Requirements_Read_MultipleFilesWithSameSections_MergesSections - - - title: Requirements Definition - requirements: - - id: ReqStream-Req-UniqueIds - title: The tool shall require each requirement to have a unique identifier. - justification: | - Unique identifiers enable unambiguous referencing of requirements in documentation, test - mappings, and traceability reports. - tags: - - requirements - tests: - - Requirements_Read_DuplicateRequirementId_ThrowsException - - Requirements_Read_BlankRequirementId_ThrowsExceptionWithFileLocation - - Requirements_Read_MultipleFilesWithDuplicateIds_ThrowsException - - - id: ReqStream-Req-RequiredTitle - title: The tool shall require each requirement to have a title. - justification: | - Titles provide human-readable descriptions of requirements, making them understandable to - stakeholders without needing to reference external documentation. - tags: - - requirements - tests: - - Requirements_Read_BlankRequirementTitle_ThrowsExceptionWithFileLocation - - - id: ReqStream-Req-ParentChild - title: The tool shall support parent-child relationships between requirements. - justification: | - Parent-child relationships enable hierarchical requirement decomposition, allowing high-level - requirements to be satisfied through lower-level requirements. - tags: - - requirements - tests: - - Requirements_Read_RequirementWithChildren_ParsesChildrenCorrectly - - TraceMatrix_Export_WithChildRequirements_ConsidersChildTests - - - id: ReqStream-Req-TestMappings - title: The tool shall support test mappings for requirements. - justification: | - Test mappings establish traceability between requirements and tests, enabling verification - that requirements are adequately tested and satisfied. - tags: - - requirements - tests: - - Requirements_Read_RequirementWithTests_ParsesTestsCorrectly - - Requirements_Read_BlankTestNameInRequirement_ThrowsExceptionWithFileLocation - - Requirements_Read_TestMappings_AppliesMappingsCorrectly - - Requirements_Read_BlankTestNameInMapping_ThrowsExceptionWithFileLocation - - Requirements_Read_BlankMappingId_ThrowsExceptionWithFileLocation - - - title: Test Integration - requirements: - - id: ReqStream-Test-ResultFiles - title: The tool shall support processing test result files. - justification: | - Processing test results enables automated verification of requirement satisfaction and - integration with existing test infrastructure. - tags: - - testing - tests: - - TraceMatrix_WithNoFiles_CreatesEmptyMatrix - - TraceMatrix_MissingFile_ThrowsFileNotFoundException - - TraceMatrix_WithMultipleFiles_AggregatesResults - - - id: ReqStream-Test-TrxFormat - title: The tool shall support TRX format test results. - justification: | - TRX is the native test result format for .NET testing frameworks, enabling seamless - integration with .NET projects. - tags: - - testing - tests: - - TraceMatrix_WithTrxFile_ParsesCorrectly - - TraceMatrix_WithFailedTests_TracksFailures - - - id: ReqStream-Test-JUnitFormat - title: The tool shall support JUnit format test results. - justification: | - JUnit format is widely used across multiple programming ecosystems, enabling cross-platform - test result integration. - tags: - - testing - tests: - - TraceMatrix_WithJUnitFile_ParsesCorrectly - - TraceMatrix_WithJUnitFailedTests_TracksFailures - - - id: ReqStream-Test-GlobPatterns - title: The tool shall support glob patterns for test result files. - justification: | - Glob patterns simplify specification of multiple test result files and enable flexible - file selection across different test runs and platforms. - tags: - - testing - tests: - - Context_Create_WithTestsPattern_ExpandsGlobPattern - - TraceMatrix_WithMixedFormats_ProcessesBoth - - - id: ReqStream-Test-SourceFiltering - title: The tool shall support source-specific test matching using filepart@testname pattern. - justification: | - Source-specific matching enables requirements to reference tests from specific test runs - or platforms, supporting platform-specific requirements validation. - tags: - - testing - tests: - - TraceMatrix_WithSourceSpecificTests_MatchesCorrectly - - TraceMatrix_WithSourceSpecificTests_DoesNotMatchOtherSources - - TraceMatrix_WithMultipleSourceSpecifiers_MatchesAllRequirements - - - id: ReqStream-Test-CaseInsensitive - title: >- - The tool shall perform case-insensitive matching of file parts in source-specific - test names. - justification: | - Case-insensitive matching reduces errors and improves usability by allowing flexible - specification of file part identifiers. - tags: - - testing - tests: - - TraceMatrix_WithSourceSpecificTests_IsCaseInsensitive - - - id: ReqStream-Test-PartialFilenames - title: The tool shall support partial filename matching for source-specific tests. - justification: | - Partial matching simplifies test specification by allowing short, memorable identifiers - rather than requiring full filename matches. - tags: - - testing - tests: - - TraceMatrix_WithSourceSpecificTests_MatchesPartialFilename - - - id: ReqStream-Test-PlainTestNames - title: The tool shall support plain test names that aggregate from all sources. - justification: | - Plain test names enable requirements to aggregate test results across all platforms and - test runs without specifying each source explicitly. - tags: - - testing - tests: - - TraceMatrix_WithPlainTestNames_MatchesAllSources - - - id: ReqStream-Test-MixedTestNames - title: >- - The tool shall support mixing plain and source-specific test names in the same - requirement. - justification: | - Mixing test name types provides flexibility for requirements that need both platform-specific - and cross-platform test coverage. - tags: - - testing - tests: - - TraceMatrix_WithMixedTestNames_MatchesAppropriately - - - id: ReqStream-Test-MultipleRequirements - title: >- - The tool shall match tests to multiple requirements with mixed filter - references. - justification: | - Supporting multiple requirements with mixed references enables efficient test reuse and - accurate traceability across different requirement types. - tags: - - testing - tests: - - TraceMatrix_WithMixedFilterAndPlainReferences_MatchesBoth - - - title: Reporting - requirements: - - id: ReqStream-Rpt-MarkdownExport - title: The tool shall export requirements to markdown format. - justification: | - Markdown export enables requirements to be included in documentation, wikis, and other - human-readable formats for stakeholder communication. - tags: - - reporting - tests: - - Program_Run_WithRequirementsExport_GeneratesReport - - Requirements_Export_SimpleRequirements_CreatesMarkdownFile - - Requirements_Export_MultipleSections_ExportsAll - - Requirements_Export_EmptyRequirements_CreatesEmptyFile - - - id: ReqStream-Rpt-HeaderDepth - title: The tool shall support configurable markdown header depth for requirements reports. - justification: | - Configurable header depth allows requirements reports to be embedded in larger documents - while maintaining proper document structure. - tags: - - reporting - tests: - - Context_Create_ReportDepth_SetsReportDepthProperty - - Requirements_Export_WithCustomDepth_UsesCorrectHeaderLevel - - - id: ReqStream-Rpt-TraceMatrix - title: The tool shall export trace matrices to markdown format. - justification: | - Trace matrix export provides visibility into test coverage and requirement satisfaction, - essential for quality assurance and compliance. - tags: - - reporting - tests: - - Program_Run_WithTraceMatrixExport_GeneratesMatrix - - TraceMatrix_Export_SimpleTraceMatrix_CreatesMarkdownFile - - TraceMatrix_Export_WithFailedTests_ShowsFailures - - TraceMatrix_Export_WithNoTests_ShowsNotSatisfied - - TraceMatrix_Export_WithNotExecutedTests_ShowsNotExecuted - - - id: ReqStream-Rpt-TraceMatrixDepth - title: The tool shall support configurable markdown header depth for trace matrices. - justification: | - Configurable header depth allows trace matrices to be embedded in larger documents while - maintaining proper document structure. - tags: - - reporting - tests: - - Context_Create_MatrixDepth_SetsMatrixDepthProperty - - Requirements_Export_WithCustomDepth_UsesCorrectHeaderLevel - - - id: ReqStream-Rpt-TagFiltering - title: The tool shall support filtering requirements by tags. - justification: | - Tag-based filtering enables selective export of requirement subsets for focused reports, - security audits, compliance documentation, and targeted reviews. - tags: - - reporting - tests: - - Context_Create_FilterArgument_ParsesTagsCorrectly - - Context_Create_FilterArgumentWithSpaces_TrimsAndParsesTagsCorrectly - - Context_Create_FilterSingleTag_ParsesCorrectly - - Requirements_Export_WithFilterTags_ExportsOnlyMatchingRequirements - - Requirements_Export_WithMultipleFilterTags_ExportsRequirementsMatchingAnyTag - - Requirements_ExportJustifications_WithFilterTags_ExportsOnlyMatchingRequirements - - TraceMatrix_Export_WithFilterTags_ExportsOnlyMatchingRequirements - - TraceMatrix_CalculateSatisfiedRequirements_WithFilterTags_CountsOnlyMatchingRequirements - - TraceMatrix_GetUnsatisfiedRequirements_WithFilterTags_ReturnsOnlyMatchingRequirements - - - id: ReqStream-Rpt-Justifications - title: The tool shall export requirement justifications to markdown format. - justification: | - Justification export enables stakeholders to understand the rationale behind - requirements, supporting design reviews, audits, and compliance activities. - tags: - - reporting - tests: - - Requirements_ExportJustifications_WithJustifications_CreatesMarkdownFile - - Requirements_ExportJustifications_WithoutJustifications_CreatesHeadersOnly - - Requirements_ExportJustifications_NestedSections_CreatesHierarchy - - - id: ReqStream-Rpt-JustificationsDepth - title: >- - The tool shall support configurable markdown header depth for justification - reports. - justification: | - Configurable header depth allows justification reports to be embedded in larger - documents while maintaining proper document structure. - tags: - - reporting - tests: - - Requirements_ExportJustifications_WithCustomDepth_UsesCorrectHeaderLevel - - - title: Logging - requirements: - - id: ReqStream-Log-FileOutput - title: The tool shall support writing output to a log file. - justification: | - Log file support enables capturing tool output for debugging, audit trails, and CI/CD - integration where console output may be ephemeral. - tags: - - logging - tests: - - Context_Create_WithLogFile_WritesToLogFile - - Context_Create_WithLogFileAndSilent_WritesToLogOnly - - Context_Dispose_WithLogFile_ClosesLogFile - - - title: Validation - requirements: - - id: ReqStream-Val-SelfValidation - title: The tool shall support self-validation mode. - justification: | - Self-validation ensures the tool's own integrity and serves as a smoke test for - installation and configuration issues. - tags: - - validation - tests: - - Program_Run_WithValidateFlag_RunsValidation - - Context_Create_ValidateFlag_SetsValidateProperty - - - id: ReqStream-Val-EnforcementMode - title: >- - The tool shall support enforcement mode to fail when requirements are - not fully tested. - justification: | - Enforcement mode enables CI/CD pipelines to block releases when requirements - lack test coverage, ensuring product quality and compliance. - tags: - - validation - tests: - - Context_Create_EnforceFlag_SetsEnforceProperty - - Program_Run_WithEnforcementAndFullySatisfiedRequirements_Succeeds - - Program_Run_WithEnforcementAndUnsatisfiedRequirements_Fails - - Program_Run_WithEnforcementAndNoTests_Fails - - Program_Run_WithEnforcementAndFailedTests_Fails - - ReqStream_EnforcementMode - - - title: Platform Support - requirements: - - id: ReqStream-Plt-Windows - title: The tool shall run on Windows operating systems. - justification: | - Windows support is essential for .NET developers who primarily work in Windows environments - and use Visual Studio. - tags: - - platform - tests: - - "windows@ReqStream_RequirementsProcessing" - - "windows@ReqStream_TraceMatrix" - - "windows@ReqStream_ReportExport" - - "windows@ReqStream_TagsFiltering" - - "windows@ReqStream_EnforcementMode" - - - id: ReqStream-Plt-Linux - title: The tool shall run on Linux operating systems. - justification: | - Linux support enables use in containerized CI/CD environments and cloud-based build systems - that typically use Linux. - tags: - - platform - tests: - - "ubuntu@ReqStream_RequirementsProcessing" - - "ubuntu@ReqStream_TraceMatrix" - - "ubuntu@ReqStream_ReportExport" - - "ubuntu@ReqStream_TagsFiltering" - - "ubuntu@ReqStream_EnforcementMode" - - - id: ReqStream-Plt-MacOS - title: The tool shall run on macOS operating systems. - justification: | - macOS support is essential for developers using Apple platforms who need to run - ReqStream locally and in CI/CD pipelines on macOS agents. - tags: - - platform - tests: - - "macos@ReqStream_RequirementsProcessing" - - "macos@ReqStream_TraceMatrix" - - "macos@ReqStream_ReportExport" - - "macos@ReqStream_TagsFiltering" - - "macos@ReqStream_EnforcementMode" - - - id: ReqStream-Plt-Net8 - title: The tool shall support .NET 8.0 runtime. - justification: | - .NET 8.0 is an LTS release, providing long-term stability and support for enterprise users. - tags: - - platform - tests: - - "dotnet8.x@ReqStream_RequirementsProcessing" - - "dotnet8.x@ReqStream_TraceMatrix" - - "dotnet8.x@ReqStream_ReportExport" - - "dotnet8.x@ReqStream_TagsFiltering" - - "dotnet8.x@ReqStream_EnforcementMode" - - - id: ReqStream-Plt-Net9 - title: The tool shall support .NET 9.0 runtime. - justification: | - .NET 9.0 support enables users to leverage the latest .NET features and performance - improvements. - tags: - - platform - tests: - - "dotnet9.x@ReqStream_RequirementsProcessing" - - "dotnet9.x@ReqStream_TraceMatrix" - - "dotnet9.x@ReqStream_ReportExport" - - "dotnet9.x@ReqStream_TagsFiltering" - - "dotnet9.x@ReqStream_EnforcementMode" - - - id: ReqStream-Plt-Net10 - title: The tool shall support .NET 10.0 runtime. - justification: | - .NET 10.0 support ensures the tool remains compatible with the latest .NET ecosystem and - future-proofs the project. - tags: - - platform - tests: - - "dotnet10.x@ReqStream_RequirementsProcessing" - - "dotnet10.x@ReqStream_TraceMatrix" - - "dotnet10.x@ReqStream_ReportExport" - - "dotnet10.x@ReqStream_TagsFiltering" - - "dotnet10.x@ReqStream_EnforcementMode" - - - title: OTS Software - requirements: - - id: ReqStream-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_SetsVersionProperty - - Context_Create_HelpFlags_SetsHelpProperty - - Context_Create_ValidateFlag_SetsValidateProperty - - Context_Create_EnforceFlag_SetsEnforceProperty - - Requirements_Read_SimpleRequirement_ParsesCorrectly - - Program_Run_WithVersionFlag_PrintsVersion - - Program_Run_WithHelpFlag_PrintsHelp - - - id: ReqStream-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: ReqStream-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: ReqStream-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: ReqStream-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: ReqStream-OTS-SonarMark - title: SonarMark shall generate a SonarCloud quality report. - justification: | - DemaConsulting.SonarMark retrieves quality-gate and metrics data from SonarCloud and - renders it as a markdown document included in the release artifacts. It runs in the - same CI pipeline that produces the TRX test results, so a successful pipeline run is - evidence that SonarMark executed without error. - tags: [ots] - tests: - - SonarMark_QualityGateRetrieval - - SonarMark_IssuesRetrieval - - SonarMark_HotSpotsRetrieval - - SonarMark_MarkdownReportGeneration +includes: + - docs/reqstream/unit-context.yaml + - docs/reqstream/unit-program.yaml + - docs/reqstream/unit-validation.yaml + - docs/reqstream/unit-requirements.yaml + - docs/reqstream/unit-trace-matrix.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 From db24b4161156af67b9eb8d8718c17cc9604ad58b Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Wed, 25 Mar 2026 22:41:52 -0400 Subject: [PATCH 07/10] Update CONTRIBUTING.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3b946e5..1de683a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -49,6 +49,8 @@ We follow a standard GitHub workflow for contributions: - [.NET SDK][dotnet-download] 8.0, 9.0, or 10.0 - Git +- Node.js (with npm, required for running JavaScript-based tools and lint scripts) +- Python 3 (with venv and pip, required for Python-based tooling used by lint scripts) - A code editor (Visual Studio, VS Code, or Rider recommended) ### Getting Started From 05dfec66cd6420599c972e3fea1b8ca1fdc00727 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 02:46:55 +0000 Subject: [PATCH 08/10] Add design documentation, move source filter comment, update reviewmark review sets Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> Agent-Logs-Url: https://github.com/demaconsulting/ReqStream/sessions/2b194e1a-0fcd-40ab-8fbf-6062639fbb37 --- .reviewmark.yaml | 7 ++ docs/design/context.md | 74 +++++++++++++ docs/design/definition.yaml | 16 +++ docs/design/introduction.md | 41 ++++++++ docs/design/program.md | 98 ++++++++++++++++++ docs/design/requirements.md | 96 +++++++++++++++++ docs/design/title.txt | 15 +++ docs/design/trace-matrix.md | 121 ++++++++++++++++++++++ docs/design/validation.md | 75 ++++++++++++++ docs/reqstream/platform-requirements.yaml | 22 ++++ requirements.yaml | 29 ------ 11 files changed, 565 insertions(+), 29 deletions(-) create mode 100644 docs/design/context.md create mode 100644 docs/design/definition.yaml create mode 100644 docs/design/introduction.md create mode 100644 docs/design/program.md create mode 100644 docs/design/requirements.md create mode 100644 docs/design/title.txt create mode 100644 docs/design/trace-matrix.md create mode 100644 docs/design/validation.md diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 8a8dcd4..a36e148 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -8,6 +8,7 @@ needs-review: - "**/*.cs" # All C# source and test files - "docs/reqstream/**/*.yaml" # Requirements files + - "docs/design/**/*.md" # Design documents - "!**/obj/**" # Exclude build output - "!**/bin/**" # Exclude build output @@ -28,6 +29,7 @@ reviews: title: Review of ReqStream Context Unit paths: - "docs/reqstream/unit-context.yaml" + - "docs/design/context.md" - "src/**/Context.cs" - "test/**/ContextTests.cs" @@ -35,6 +37,7 @@ reviews: title: Review of ReqStream Program Unit paths: - "docs/reqstream/unit-program.yaml" + - "docs/design/program.md" - "src/**/Program.cs" - "test/**/ProgramTests.cs" @@ -42,12 +45,15 @@ reviews: title: Review of ReqStream Validation Unit paths: - "docs/reqstream/unit-validation.yaml" + - "docs/design/validation.md" - "src/**/Validation.cs" + - "test/**/ProgramTests.cs" - id: ReqStream-Requirements title: Review of ReqStream Requirements Unit paths: - "docs/reqstream/unit-requirements.yaml" + - "docs/design/requirements.md" - "src/**/Requirement.cs" - "src/**/Requirements.cs" - "src/**/Section.cs" @@ -58,6 +64,7 @@ reviews: title: Review of ReqStream TraceMatrix Unit paths: - "docs/reqstream/unit-trace-matrix.yaml" + - "docs/design/trace-matrix.md" - "src/**/TraceMatrix.cs" - "test/**/TraceMatrixTests.cs" - "test/**/TraceMatrixReadTests.cs" diff --git a/docs/design/context.md b/docs/design/context.md new file mode 100644 index 0000000..b698189 --- /dev/null +++ b/docs/design/context.md @@ -0,0 +1,74 @@ +# Context Design + +## Overview + +The `Context` class is responsible for parsing command-line arguments and providing a unified interface for +program output. It is the sole source of truth for all runtime configuration options and controls whether +output is written to the console, a log file, or suppressed entirely. + +## Structure + +`Context` is a `sealed` class implementing `IDisposable`. It is instantiated exclusively through the static +factory method `Context.Create(string[] args)`, which keeps the constructor private. + +### Properties + +All properties are immutable after construction (`private init`): + +| Property | Type | Description | +| :--- | :--- | :--- | +| `Version` | `bool` | `--version` flag was specified | +| `Help` | `bool` | `--help` flag was specified | +| `Silent` | `bool` | `--silent` flag suppresses console output | +| `Validate` | `bool` | `--validate` flag triggers self-validation | +| `Enforce` | `bool` | `--enforce` flag enables coverage enforcement | +| `FilterTags` | `HashSet?` | Tag filter set; `null` if not specified | +| `RequirementsFiles` | `List` | Expanded paths from `--requirements` glob pattern | +| `TestFiles` | `List` | Expanded paths from `--tests` glob pattern | +| `RequirementsReport` | `string?` | Output path for `--report` | +| `ReportDepth` | `int` | Markdown heading depth for the report (default: 1) | +| `Matrix` | `string?` | Output path for `--matrix` | +| `MatrixDepth` | `int` | Markdown heading depth for the matrix (default: 1) | +| `JustificationsFile` | `string?` | Output path for `--justifications` | +| `JustificationsDepth` | `int` | Markdown heading depth for justifications (default: 1) | +| `ResultsFile` | `string?` | Output path for `--results` (validation test results) | +| `ExitCode` | `int` | Returns 0 (success) or 1 (errors reported) | + +### Output Methods + +| Method | Behavior | +| :--- | :--- | +| `WriteLine(string)` | Writes to console (unless `Silent`) and optional log file | +| `WriteError(string)` | Writes to stderr in red (unless `Silent`), writes to log file, sets `_hasErrors = true` | + +### Argument Parsing + +`Create` uses a `while` loop with a `switch` statement over each argument token. Arguments requiring a +value consume the next token from the array. An `ArgumentException` is thrown for unknown arguments or +missing values. + +Glob patterns (from `--requirements` and `--tests`) are expanded using +`Microsoft.Extensions.FileSystemGlobbing.Matcher` against the current working directory. + +### Log File + +If `--log ` is specified, a `StreamWriter` is opened with `AutoFlush = true`. The writer is stored +in the private `_logWriter` field and is closed by `Dispose()`. + +## Key Design Decisions + +- **Private constructor with factory method**: Enforces that instances are only created through `Create`, + keeping validation logic centralized. +- **Immutable properties**: All configuration properties use `private init` to prevent accidental mutation + after parsing. +- **Glob expansion at parse time**: File lists are fully resolved during argument parsing so the rest of the + program works with concrete file paths. +- **Error tracking via `WriteError`**: Any code path that calls `WriteError` automatically marks the session + as having errors, ensuring a non-zero exit code without requiring explicit error propagation. + +## Relationships + +- **Created by**: `Program.Main` passes `string[] args` to `Context.Create` +- **Consumed by**: `Program.Run`, `Program.ProcessRequirements`, `Validation.Run`, and all export methods + use `Context` for output and configuration +- **Owns**: Optional `StreamWriter` for log file output (released via `IDisposable`) diff --git a/docs/design/definition.yaml b/docs/design/definition.yaml new file mode 100644 index 0000000..c6e7f95 --- /dev/null +++ b/docs/design/definition.yaml @@ -0,0 +1,16 @@ +--- +resource-path: + - docs/design + - docs/template +input-files: + - docs/design/title.txt + - docs/design/introduction.md + - docs/design/context.md + - docs/design/program.md + - docs/design/validation.md + - docs/design/requirements.md + - docs/design/trace-matrix.md +template: template.html +table-of-contents: true +number-sections: true +--- diff --git a/docs/design/introduction.md b/docs/design/introduction.md new file mode 100644 index 0000000..8ec6e42 --- /dev/null +++ b/docs/design/introduction.md @@ -0,0 +1,41 @@ +# Introduction + +This document describes the internal design of the ReqStream tool, a .NET command-line application for managing +software requirements in YAML format. + +## Purpose + +The purpose of this document is to define the design of each software unit that makes up the ReqStream tool. +It describes the structure, responsibilities, key design decisions, and relationships of each unit, providing +a reference for developers maintaining or extending the tool. + +## Scope + +This document covers the design of the following software units: + +- **Context** — command-line argument parsing and program output +- **Program** — application entry point and top-level orchestration +- **Validation** — self-validation test execution +- **Requirements** — YAML requirements model and export +- **TraceMatrix** — test result integration and coverage computation + +This document does not cover deployment, build procedures, or external tool integrations beyond their interface +to ReqStream. + +## Document Conventions + +Throughout this document: + +- Software units correspond to one or more C# source files in `src/DemaConsulting.ReqStream/` +- Code elements such as class names, method names, and properties are written in `monospace` +- Each unit section describes: overview, structure, key design decisions, and relationships to other units + +## References + +- [ReqStream User Guide][guide] +- [ReqStream Requirements Specification][requirements] +- [ReqStream Repository][repo] + +[guide]: https://github.com/demaconsulting/ReqStream/blob/main/docs/guide/guide.md +[requirements]: https://github.com/demaconsulting/ReqStream +[repo]: https://github.com/demaconsulting/ReqStream diff --git a/docs/design/program.md b/docs/design/program.md new file mode 100644 index 0000000..d456d38 --- /dev/null +++ b/docs/design/program.md @@ -0,0 +1,98 @@ +# Program Design + +## Overview + +The `Program` class is the application entry point and top-level orchestrator. It coordinates the processing +pipeline based on the flags parsed by `Context`, delegating to the appropriate units in priority order. + +## Structure + +`Program` is an `internal static` class with the following members: + +### Version Property + +```csharp +public static string Version { get; } +``` + +Reads the informational version string from `AssemblyInformationalVersionAttribute` on the executing +assembly. Falls back to the assembly version, then `"Unknown"` if neither is available. + +### Main Entry Point + +```csharp +private static int Main(string[] args) +``` + +The `Main` method: + +1. Creates a `Context` via `Context.Create(args)` +2. Calls `Run(context)` to execute the program logic +3. Returns `context.ExitCode` + +Caught exceptions and their handling: + +| Exception | Handling | +| :--- | :--- | +| `ArgumentException` | Prints message to stderr, returns exit code 1 | +| `InvalidOperationException` | Prints message to stderr, returns exit code 1 | +| All other exceptions | Prints message to stderr, re-throws to generate event log entries | + +### Run Method + +```csharp +public static void Run(Context context) +``` + +Executes the program logic in strict priority order: + +1. **Version** — if `context.Version` is set, prints the version string and returns +2. **Banner** — prints the application banner via `PrintBanner` +3. **Help** — if `context.Help` is set, prints usage via `PrintHelp` and returns +4. **Self-Validation** — if `context.Validate` is set, delegates to `Validation.Run` and returns +5. **Requirements Processing** — calls `ProcessRequirements` + +`Run` is `public` to enable direct invocation from self-validation tests without going through `Main`. + +### ProcessRequirements Method + +```csharp +private static void ProcessRequirements(Context context) +``` + +Loads and processes requirements files in the following order: + +1. If no requirements files are specified, prints a message and returns +2. Calls `Requirements.Read` to load and merge all requirements files +3. If `--report` was specified, calls `requirements.Export` +4. If `--justifications` was specified, calls `requirements.ExportJustifications` +5. If test files are specified, constructs a `TraceMatrix` +6. If `--matrix` was specified, calls `traceMatrix.Export` +7. If `--enforce` was specified, calls `EnforceRequirementsCoverage` + +### EnforceRequirementsCoverage Method + +```csharp +private static void EnforceRequirementsCoverage(Context context, TraceMatrix? traceMatrix) +``` + +Validates that all requirements (within any tag filter) are satisfied by passing tests: + +- If no trace matrix is available, reports an error via `context.WriteError` +- Calls `traceMatrix.CalculateSatisfiedRequirements` to get totals +- If unsatisfied requirements exist, lists each ID via `context.WriteError` + +## Key Design Decisions + +- **Priority-based dispatch**: The `Run` method uses an explicit priority order rather than flags being + independent, ensuring deterministic behavior when multiple flags are combined. +- **Public `Run` for testability**: Making `Run` public allows `Validation` tests to call it directly with + a controlled `Context`, avoiding the need to spawn a separate process. +- **Exception handling at the boundary**: `Main` catches expected exception types to produce clean error + messages; unexpected exceptions are re-thrown to allow operating system event logging. + +## Relationships + +- **Uses**: `Context` (created in `Main`), `Requirements` (via `ProcessRequirements`), `TraceMatrix` + (via `ProcessRequirements`), `Validation` (via `Run`) +- **Called by**: Operating system (via `Main`), `Validation` test methods (via `Run`) diff --git a/docs/design/requirements.md b/docs/design/requirements.md new file mode 100644 index 0000000..51ed468 --- /dev/null +++ b/docs/design/requirements.md @@ -0,0 +1,96 @@ +# Requirements Design + +## Overview + +The Requirements unit models the requirements tree loaded from one or more YAML files. It is composed of +three classes: `Requirement` (a leaf data model), `Section` (a tree node), and `Requirements` (the root +that handles loading, validation, and export). + +## Structure + +### Requirement Class (`Requirement.cs`) + +`Requirement` is a simple data model representing a single requirement: + +| Property | Type | Description | +| :--- | :--- | :--- | +| `Id` | `string` | Unique requirement identifier (e.g., `CLI-001`) | +| `Title` | `string` | Human-readable requirement title | +| `Justification` | `string?` | Optional justification text for non-tested requirements | +| `Tests` | `List` | Test names that satisfy this requirement | +| `Children` | `List` | IDs of child requirements (hierarchical composition) | +| `Tags` | `List` | Tags used for filtering during export | + +Test names may include a source filter prefix in the form `sourceFilter@testName`, which restricts matching +to test result files whose base name contains the filter substring. + +### Section Class (`Section.cs`) + +`Section` is a tree node grouping related requirements: + +| Property | Type | Description | +| :--- | :--- | :--- | +| `Title` | `string` | Section heading text | +| `Requirements` | `List` | Requirements directly within this section | +| `Sections` | `List
` | Child sections (recursive nesting) | + +### Requirements Class (`Requirements.cs`) + +`Requirements` extends `Section` and is the root of the requirements tree. It owns loading, merging, +validation, and export. + +#### Reading YAML Files + +```csharp +public static Requirements Read(params string[] paths) +``` + +- Creates a single `Requirements` instance and calls `ReadFile` for each path +- `ReadFile` deserializes the YAML using `YamlDotNet` with `CamelCaseNamingConvention` +- Supports an `includes:` field in YAML documents to recursively include other files +- Cycle detection for included files is maintained in the private `_includedFiles` `HashSet` +- Duplicate requirement IDs are detected using the private `_allRequirements` dictionary; a duplicate + raises `InvalidOperationException` +- After all files are read, `ValidateCycles()` checks for cyclic parent/child references among + requirements + +#### YAML Deserialization + +Internal private classes (`YamlDocument`, `YamlSection`, `YamlRequirement`, `YamlMapping`) mirror the YAML +structure and are mapped to the public model after deserialization. A `mappings:` field in the YAML +document allows test links to be added to requirements separately from their definition. + +#### Export + +```csharp +public void Export(string filePath, int depth = 1, HashSet? filterTags = null) +``` + +Exports requirements to a Markdown file. If `filterTags` is non-null, only requirements with at least one +matching tag are included in the output. The `depth` parameter controls the starting Markdown heading level +(e.g., `depth: 2` produces `##` headings for top-level sections). + +```csharp +public void ExportJustifications(string filePath, int depth = 1, HashSet? filterTags = null) +``` + +Exports justification text for requirements that have a `Justification` property set. Applies the same +tag filter and depth logic as `Export`. + +## Key Design Decisions + +- **YAML private inner model**: Using private `Yaml*` classes as deserialization targets isolates the + public API from YAML naming conventions and allows flexible mapping. +- **Single-pass cycle detection for includes**: Tracking included file paths in a `HashSet` before + recursing prevents infinite loops from circular `includes:` references. +- **Duplicate ID detection at load time**: Checking for duplicate IDs during file reading gives an early, + clear error before any processing occurs. +- **Tag filtering at export time**: Filtering is applied during export rather than at load time, allowing + the same `Requirements` tree to be exported multiple times with different filters. + +## Relationships + +- **Created by**: `Program.ProcessRequirements` via `Requirements.Read` +- **Used by**: `Program.ProcessRequirements` (for export), `TraceMatrix` (to enumerate test names and + compute coverage) +- **Depends on**: `YamlDotNet` (deserialization), standard file I/O diff --git a/docs/design/title.txt b/docs/design/title.txt new file mode 100644 index 0000000..dc42540 --- /dev/null +++ b/docs/design/title.txt @@ -0,0 +1,15 @@ +--- +title: ReqStream Design +subtitle: Software Design Specification for the ReqStream Tool +author: DEMA Consulting +description: Software Design Specification describing the internal design of the ReqStream tool's software units +lang: en-US +keywords: + - ReqStream + - Design + - Specification + - .NET + - YAML + - Command-Line Tool + - Software Units +--- diff --git a/docs/design/trace-matrix.md b/docs/design/trace-matrix.md new file mode 100644 index 0000000..eecf11b --- /dev/null +++ b/docs/design/trace-matrix.md @@ -0,0 +1,121 @@ +# Trace Matrix Design + +## Overview + +The `TraceMatrix` class maps test execution results to requirements, computing which requirements are +satisfied by passing tests. It supports TRX and JUnit test result formats via the +`DemaConsulting.TestResults` library. + +## Structure + +### Supporting Records + +#### TestMetrics + +```csharp +public record TestMetrics(int Passes, int Fails) +``` + +Aggregates pass and fail counts for a test name: + +| Member | Description | +| :--- | :--- | +| `Passes` | Number of passing executions | +| `Fails` | Number of failing executions | +| `Executed` | Computed: `Passes + Fails` | +| `AllPassed` | `true` when `Executed > 0` and `Fails == 0` | + +#### TestExecution + +```csharp +public record TestExecution(string FileBaseName, string Name, TestMetrics Metrics) +``` + +Represents a single test execution from a specific result file. `FileBaseName` is the base name of the +result file (file name without extension, e.g., `windows-latest-results` from `windows-latest-results.trx`). +It is used for source filter prefix matching: a prefix like `windows` matches any `FileBaseName` that +contains the substring `"windows"`. + +### TraceMatrix Class + +`TraceMatrix` is a `public` class. Its constructor accepts a `Requirements` object and one or more test +result file paths. + +#### Constructor + +```csharp +public TraceMatrix(Requirements requirements, params string[] testResultFiles) +``` + +For each test result file: + +1. Deserializes the file using `DemaConsulting.TestResults.IO.Serializer.Deserialize` (auto-detects + TRX or JUnit from the file content) +2. For each test result, creates a `TestExecution` keyed by test name and stores it in the private + `_testExecutions` dictionary +3. Wraps parse failures in `InvalidOperationException` with the file path included in the message + +#### GetTestResult + +```csharp +public TestMetrics GetTestResult(string testName) +``` + +Resolves and aggregates metrics for a given test name. If the name contains a source filter prefix +(`sourceFilter@testName`), only executions from files whose base name contains the filter substring +are included. Returns a zero metric (`0` passes, `0` fails) if no matching executions are found. + +#### CalculateSatisfiedRequirements + +```csharp +public (int satisfied, int total) CalculateSatisfiedRequirements(HashSet? filterTags) +``` + +Returns the count of satisfied requirements versus total requirements. A requirement is satisfied when: + +- It has at least one test name that resolves to `AllPassed == true`, **or** +- All of its child requirements (referenced by `Children`) are satisfied (recursive) + +Tag filtering is applied: if `filterTags` is non-null, only requirements with at least one matching tag +are counted. + +#### GetUnsatisfiedRequirements + +```csharp +public List GetUnsatisfiedRequirements(HashSet? filterTags) +``` + +Returns the IDs of requirements that are not satisfied. Used by `Program.EnforceRequirementsCoverage` +to report which requirements are missing coverage. + +#### Export + +```csharp +public void Export(string filePath, int depth, HashSet? filterTags) +``` + +Exports a Markdown trace matrix with three sections: + +1. **Summary** — overall pass/fail statistics +2. **Requirements** — table of requirements with their test links and satisfaction status +3. **Testing** — table of tests with their pass/fail counts + +## Key Design Decisions + +- **Source filter prefix**: The `sourceFilter@testName` convention allows requirements to constrain + which CI platform's test results must pass, enabling cross-platform traceability without requiring + separate requirements per platform. +- **Aggregation across files**: Multiple test result files are aggregated into a single dictionary by + test name, so the same test run on multiple machines counts as multiple executions. +- **Child requirement inheritance**: A parent requirement is satisfied if all its children are + satisfied, enabling hierarchical requirements without requiring each parent to have its own direct + test links. +- **Zero metric for missing tests**: Returning `TestMetrics(0, 0)` for unresolved tests keeps + downstream logic uniform — `AllPassed` is `false`, so the requirement is correctly marked unsatisfied. + +## Relationships + +- **Created by**: `Program.ProcessRequirements` when test files are specified +- **Uses**: `Requirements` (for requirement and test name enumeration), `DemaConsulting.TestResults` + (for deserializing TRX and JUnit files) +- **Used by**: `Program.ProcessRequirements` (for matrix export and enforcement) diff --git a/docs/design/validation.md b/docs/design/validation.md new file mode 100644 index 0000000..08ee310 --- /dev/null +++ b/docs/design/validation.md @@ -0,0 +1,75 @@ +# Validation Design + +## Overview + +The `Validation` class provides ReqStream's self-validation capability. When invoked with the `--validate` +flag, it runs a suite of functional tests against the `Program` class itself, verifying that the core +features of ReqStream work correctly on the current platform and runtime. + +## Structure + +`Validation` is a `public static` class containing one public method and several private helpers. + +### Run Method + +```csharp +public static void Run(Context context) +``` + +Orchestrates the self-validation process: + +1. Prints a validation header with system information (tool version, machine name, OS, .NET runtime, + timestamp) +2. Creates a `DemaConsulting.TestResults.TestResults` collection named `"ReqStream Self-Validation"` +3. Runs five functional tests (see below) +4. Prints a summary of total, passed, and failed tests +5. If `context.ResultsFile` is set, writes results using `DemaConsulting.TestResults.IO.Serializer` + +### Test Suite + +Each test method creates temporary files in a temporary directory, invokes `Program.Run()` with a +constructed `Context`, and inspects the output files or `Context.ExitCode` to verify behavior. + +| Test Name | What It Verifies | +| :--- | :--- | +| `ReqStream_RequirementsProcessing` | Reading and processing requirements YAML files | +| `ReqStream_TraceMatrix` | Trace matrix construction from test result files | +| `ReqStream_ReportExport` | Exporting requirements to a markdown report | +| `ReqStream_TagsFiltering` | Tag-based filtering of requirements during export | +| `ReqStream_EnforcementMode` | Enforcement of requirements coverage | + +### Test Result Naming + +Test results are named using the base name of the results file as a source prefix: + +```text +windows@ReqStream_RequirementsProcessing +``` + +This allows CI pipelines running on multiple platforms to aggregate results while keeping per-platform +attribution. The prefix is matched as a substring of the result file's base name, so a prefix of `windows` +matches a file such as `windows-latest-results.trx`. + +### Results File Output + +If `context.ResultsFile` is specified, the collected `TestResults` object is serialized using +`DemaConsulting.TestResults.IO.Serializer.Serialize`. The format (TRX or JUnit) is determined +automatically from the file extension. + +## Key Design Decisions + +- **In-process testing**: Tests run `Program.Run()` directly in the same process, using temporary + directories and files. This avoids the complexity of spawning child processes while still exercising + the full code path. +- **Public class for testability**: `Validation` is `public` so that unit tests in the test project can + also call it directly. +- **Source filter prefix in test names**: Using `basename@testName` allows the same logical test to be + tracked independently per platform when results from multiple CI agents are merged. +- **Error propagation via `Context`**: Test failures are reported through `context.WriteError`, which + automatically sets the exit code to 1 without requiring explicit error handling in callers. + +## Relationships + +- **Invoked by**: `Program.Run` when `context.Validate` is set +- **Uses**: `Program.Run` (to execute the program under test), `Context` (for output and configuration), + `DemaConsulting.TestResults` (for collecting and serializing test results) diff --git a/docs/reqstream/platform-requirements.yaml b/docs/reqstream/platform-requirements.yaml index 593294c..2f68a8b 100644 --- a/docs/reqstream/platform-requirements.yaml +++ b/docs/reqstream/platform-requirements.yaml @@ -1,3 +1,25 @@ +# Source Filter Prefixes for Platform and Framework Requirements +# +# Test links can include a source filter prefix 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 +# +# 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. +# --- sections: - title: ReqStream Requirements diff --git a/requirements.yaml b/requirements.yaml index 42516f2..f82592c 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -1,32 +1,3 @@ -# 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 -# --- includes: - docs/reqstream/unit-context.yaml From 32f6058583ab4dd2d69dbd6b2251549244d65b36 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 02:55:53 +0000 Subject: [PATCH 09/10] Add ValidationTests.cs and update review set and requirements links Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> Agent-Logs-Url: https://github.com/demaconsulting/ReqStream/sessions/c78e09f2-c209-4b61-9988-b016c910e62e --- .reviewmark.yaml | 2 +- docs/reqstream/unit-validation.yaml | 3 + .../ValidationTests.cs | 164 ++++++++++++++++++ 3 files changed, 168 insertions(+), 1 deletion(-) create mode 100644 test/DemaConsulting.ReqStream.Tests/ValidationTests.cs diff --git a/.reviewmark.yaml b/.reviewmark.yaml index a36e148..b7d4830 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -47,7 +47,7 @@ reviews: - "docs/reqstream/unit-validation.yaml" - "docs/design/validation.md" - "src/**/Validation.cs" - - "test/**/ProgramTests.cs" + - "test/**/ValidationTests.cs" - id: ReqStream-Requirements title: Review of ReqStream Requirements Unit diff --git a/docs/reqstream/unit-validation.yaml b/docs/reqstream/unit-validation.yaml index db5d759..4631b1a 100644 --- a/docs/reqstream/unit-validation.yaml +++ b/docs/reqstream/unit-validation.yaml @@ -14,6 +14,9 @@ sections: tests: - Program_Run_WithValidateFlag_RunsValidation - Context_Create_ValidateFlag_SetsValidateProperty + - Validation_Run_WithSilentContext_CompletesSuccessfully + - Validation_Run_WithTrxResultsFile_WritesTrxFile + - Validation_Run_WithXmlResultsFile_WritesXmlFile - id: ReqStream-Val-EnforcementMode title: >- diff --git a/test/DemaConsulting.ReqStream.Tests/ValidationTests.cs b/test/DemaConsulting.ReqStream.Tests/ValidationTests.cs new file mode 100644 index 0000000..23ece0d --- /dev/null +++ b/test/DemaConsulting.ReqStream.Tests/ValidationTests.cs @@ -0,0 +1,164 @@ +// Copyright (c) 2026 DEMA Consulting +// +// Permission is hereby granted, free of charge, to any person obtaining a copy +// of this software and associated documentation files (the "Software"), to deal +// in the Software without restriction, including without limitation the rights +// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +// copies of the Software, and to permit persons to whom the Software is +// furnished to do so, subject to the following conditions: +// +// The above copyright notice and this permission notice shall be included in all +// copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +// SOFTWARE. + +namespace DemaConsulting.ReqStream.Tests; + +/// +/// Unit tests for the Validation class. +/// +[TestClass] +public class ValidationTests +{ + private string _testDirectory = string.Empty; + + /// + /// Initialize test by creating a temporary test directory. + /// + [TestInitialize] + public void TestInitialize() + { + _testDirectory = Path.Combine(Path.GetTempPath(), $"reqstream_test_{Guid.NewGuid()}"); + Directory.CreateDirectory(_testDirectory); + } + + /// + /// Clean up test by deleting the temporary test directory. + /// + [TestCleanup] + public void TestCleanup() + { + if (Directory.Exists(_testDirectory)) + { + Directory.Delete(_testDirectory, recursive: true); + } + } + + /// + /// Test that Run throws ArgumentNullException when context is null. + /// + [TestMethod] + public void Validation_Run_WithNullContext_ThrowsArgumentNullException() + { + // Arrange - nothing to arrange; null is the input + + // Act + Assert - calling Run with null should throw ArgumentNullException + Assert.ThrowsExactly(() => Validation.Run(null!)); + } + + /// + /// Test that Run completes successfully with a silent context and log file. + /// + [TestMethod] + public void Validation_Run_WithSilentContext_CompletesSuccessfully() + { + // Arrange - create a log file path and a silent context + var logFile = Path.Combine(_testDirectory, "validation.log"); + + // Act - run validation and dispose context to flush the log file + using (var context = Context.Create(["--silent", "--log", logFile])) + { + Validation.Run(context); + + // Validation should succeed with exit code 0 + Assert.AreEqual(0, context.ExitCode); + } + + // Assert - log file must exist and contain expected validation output + Assert.IsTrue(File.Exists(logFile), "Log file should exist"); + var logContent = File.ReadAllText(logFile); + Assert.Contains("DEMA Consulting ReqStream", logContent); + Assert.Contains("ReqStream Version", logContent); + Assert.Contains("ReqStream_RequirementsProcessing - Passed", logContent); + Assert.Contains("ReqStream_TraceMatrix - Passed", logContent); + Assert.Contains("ReqStream_ReportExport - Passed", logContent); + Assert.Contains("ReqStream_TagsFiltering - Passed", logContent); + Assert.Contains("ReqStream_EnforcementMode - Passed", logContent); + Assert.Contains("Total Tests: 5", logContent); + Assert.Contains("Passed: 5", logContent); + Assert.Contains("Failed: 0", logContent); + } + + /// + /// Test that Run writes a TRX results file when the results path has a .trx extension. + /// + [TestMethod] + public void Validation_Run_WithTrxResultsFile_WritesTrxFile() + { + // Arrange - create a results file path with .trx extension and a silent context + var resultsFile = Path.Combine(_testDirectory, "validation-results.trx"); + + // Act - run validation and dispose context to flush output + using (var context = Context.Create(["--silent", "--results", resultsFile])) + { + Validation.Run(context); + + // Validation should succeed with exit code 0 + Assert.AreEqual(0, context.ExitCode); + } + + // Assert - TRX file must exist and contain valid TRX XML content + Assert.IsTrue(File.Exists(resultsFile), "TRX results file should exist"); + var trxContent = File.ReadAllText(resultsFile); + Assert.StartsWith(" + /// Test that Run writes a JUnit XML results file when the results path has a .xml extension. + /// + [TestMethod] + public void Validation_Run_WithXmlResultsFile_WritesXmlFile() + { + // Arrange - create a results file path with .xml extension and a silent context + var resultsFile = Path.Combine(_testDirectory, "validation-results.xml"); + + // Act - run validation and dispose context to flush output + using (var context = Context.Create(["--silent", "--results", resultsFile])) + { + Validation.Run(context); + + // Validation should succeed with exit code 0 + Assert.AreEqual(0, context.ExitCode); + } + + // Assert - XML file must exist and contain valid JUnit XML content + Assert.IsTrue(File.Exists(resultsFile), "JUnit XML results file should exist"); + var xmlContent = File.ReadAllText(resultsFile); + Assert.StartsWith(" + /// Test that Run reports an error when the results file has an unsupported extension. + /// + [TestMethod] + public void Validation_Run_WithInvalidResultsExtension_ReportsError() + { + // Arrange - create a results file path with an unsupported .invalid extension + var resultsFile = Path.Combine(_testDirectory, "validation-results.invalid"); + + // Act - run validation and dispose context to flush output + using var context = Context.Create(["--silent", "--results", resultsFile]); + Validation.Run(context); + + // Assert - exit code must be 1 indicating an error was reported for the unsupported format + Assert.AreEqual(1, context.ExitCode); + } +} From c6a56144d6d841f45179726f3d389091b898a6d0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 03:51:21 +0000 Subject: [PATCH 10/10] Fix issues identified by code-review agent review of all review sets Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> Agent-Logs-Url: https://github.com/demaconsulting/ReqStream/sessions/c0d6ebe8-9cf3-41ce-b852-d85ca00b62f5 --- docs/design/program.md | 6 ++- docs/design/validation.md | 14 ------- docs/reqstream/unit-context.yaml | 10 +++++ docs/reqstream/unit-program.yaml | 60 ++++++++++++++++++++++++++- docs/reqstream/unit-requirements.yaml | 10 ----- docs/reqstream/unit-trace-matrix.yaml | 2 +- 6 files changed, 75 insertions(+), 27 deletions(-) diff --git a/docs/design/program.md b/docs/design/program.md index d456d38..185dbf3 100644 --- a/docs/design/program.md +++ b/docs/design/program.md @@ -80,7 +80,11 @@ Validates that all requirements (within any tag filter) are satisfied by passing - If no trace matrix is available, reports an error via `context.WriteError` - Calls `traceMatrix.CalculateSatisfiedRequirements` to get totals -- If unsatisfied requirements exist, lists each ID via `context.WriteError` +- If unsatisfied requirements exist: + - Calls `traceMatrix.GetUnsatisfiedRequirements(context.FilterTags)` to get the list + - Writes a header line: `"Unsatisfied requirements:"` + - Lists each unsatisfied requirement ID via `context.WriteError` + - Writes a summary: `"Error: Only {satisfied} of {total} requirements are satisfied with tests."` ## Key Design Decisions diff --git a/docs/design/validation.md b/docs/design/validation.md index 08ee310..c9e2e4a 100644 --- a/docs/design/validation.md +++ b/docs/design/validation.md @@ -38,18 +38,6 @@ constructed `Context`, and inspects the output files or `Context.ExitCode` to ve | `ReqStream_TagsFiltering` | Tag-based filtering of requirements during export | | `ReqStream_EnforcementMode` | Enforcement of requirements coverage | -### Test Result Naming - -Test results are named using the base name of the results file as a source prefix: - -```text -windows@ReqStream_RequirementsProcessing -``` - -This allows CI pipelines running on multiple platforms to aggregate results while keeping per-platform -attribution. The prefix is matched as a substring of the result file's base name, so a prefix of `windows` -matches a file such as `windows-latest-results.trx`. - ### Results File Output If `context.ResultsFile` is specified, the collected `TestResults` object is serialized using @@ -63,8 +51,6 @@ automatically from the file extension. the full code path. - **Public class for testability**: `Validation` is `public` so that unit tests in the test project can also call it directly. -- **Source filter prefix in test names**: Using `basename@testName` allows the same logical test to be - tracked independently per platform when results from multiple CI agents are merged. - **Error propagation via `Context`**: Test failures are reported through `context.WriteError`, which automatically sets the exit code to 1 without requiring explicit error handling in callers. diff --git a/docs/reqstream/unit-context.yaml b/docs/reqstream/unit-context.yaml index 7750180..a6e5896 100644 --- a/docs/reqstream/unit-context.yaml +++ b/docs/reqstream/unit-context.yaml @@ -59,6 +59,16 @@ sections: - Context_Create_MissingLogFilename_ThrowsException - Context_Create_MissingResultsFilename_ThrowsException + - id: ReqStream-Req-GlobPatterns + title: The tool shall support glob patterns for requirements files. + justification: | + Glob patterns enable flexible file selection and reduce the need for explicit file listing, + making the tool easier to use in various project structures. + tags: + - cli + tests: + - Context_Create_WithRequirementsPattern_ExpandsGlobPattern + - id: ReqStream-Cmd-ExitCode title: The tool shall return a non-zero exit code on failure. justification: | diff --git a/docs/reqstream/unit-program.yaml b/docs/reqstream/unit-program.yaml index dd2fc55..1fbd101 100644 --- a/docs/reqstream/unit-program.yaml +++ b/docs/reqstream/unit-program.yaml @@ -1,4 +1,62 @@ --- sections: - title: ReqStream Requirements - sections: [] + sections: + - title: Program Orchestration + requirements: + - id: ReqStream-Prog-Version + title: The tool shall print version information and exit when the version flag is provided. + justification: | + Printing version information and exiting immediately allows callers to query the installed + version without triggering any other processing, supporting scripted compatibility checks. + tags: + - cli + tests: + - Program_Run_WithVersionFlag_PrintsVersion + + - id: ReqStream-Prog-Help + title: The tool shall print usage help and exit when the help flag is provided. + justification: | + Printing usage help and exiting immediately gives users quick access to command-line + options without requiring separate documentation or triggering unintended processing. + tags: + - cli + tests: + - Program_Run_WithHelpFlag_PrintsHelp + + - id: ReqStream-Prog-Validate + title: The tool shall run self-validation when the validate flag is provided. + justification: | + Self-validation allows the tool to test its own behavior in the target environment, + providing confidence that the installation is correct and the tool operates as expected. + tags: + - cli + tests: + - Program_Run_WithValidateFlag_RunsValidation + - Program_Run_WithValidateAndResults_WritesResultsFile + + - id: ReqStream-Prog-Requirements + title: The tool shall load and process requirements files when invoked without special flags. + justification: | + Loading and processing requirements files is the primary function of the tool, enabling + generation of reports and trace matrices from structured requirements data. + tags: + - requirements + tests: + - Program_Run_WithNoRequirementsFiles_ShowsMessage + - Program_Run_WithRequirementsFiles_ProcessesSuccessfully + - Program_Run_WithRequirementsExport_GeneratesReport + - Program_Run_WithTraceMatrixExport_GeneratesMatrix + + - id: ReqStream-Prog-Enforce + title: The tool shall enforce requirements coverage and fail when requirements are unsatisfied. + justification: | + Enforcement prevents unverified requirements from passing silently through a CI/CD pipeline, + ensuring that every requirement is backed by at least one passing test before a build succeeds. + tags: + - requirements + tests: + - Program_Run_WithEnforcementAndFullySatisfiedRequirements_Succeeds + - Program_Run_WithEnforcementAndUnsatisfiedRequirements_Fails + - Program_Run_WithEnforcementAndNoTests_Fails + - Program_Run_WithEnforcementAndFailedTests_Fails diff --git a/docs/reqstream/unit-requirements.yaml b/docs/reqstream/unit-requirements.yaml index 1aeb0aa..0f78458 100644 --- a/docs/reqstream/unit-requirements.yaml +++ b/docs/reqstream/unit-requirements.yaml @@ -16,16 +16,6 @@ sections: - Program_Run_WithRequirementsFiles_ProcessesSuccessfully - Requirements_Read_ComplexStructure_ParsesCorrectly - - id: ReqStream-Req-GlobPatterns - title: The tool shall support glob patterns for requirements files. - justification: | - Glob patterns enable flexible file selection and reduce the need for explicit file listing, - making the tool easier to use in various project structures. - tags: - - requirements - tests: - - Context_Create_WithRequirementsPattern_ExpandsGlobPattern - - id: ReqStream-Req-Validation title: The tool shall validate requirements file structure. justification: | diff --git a/docs/reqstream/unit-trace-matrix.yaml b/docs/reqstream/unit-trace-matrix.yaml index b14eb5d..52e7f1f 100644 --- a/docs/reqstream/unit-trace-matrix.yaml +++ b/docs/reqstream/unit-trace-matrix.yaml @@ -166,7 +166,7 @@ sections: - reporting tests: - Context_Create_MatrixDepth_SetsMatrixDepthProperty - - Requirements_Export_WithCustomDepth_UsesCorrectHeaderLevel + - TraceMatrix_Export_WithCustomDepth_UsesCorrectHeaderLevel - id: ReqStream-Rpt-TagFiltering title: The tool shall support filtering requirements by tags.