diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index a3c61a7..decdd34 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -33,7 +33,7 @@ ] }, "demaconsulting.buildmark": { - "version": "0.4.0", + "version": "0.4.1", "commands": [ "buildmark" ] @@ -43,6 +43,12 @@ "commands": [ "versionmark" ] + }, + "demaconsulting.reviewmark": { + "version": "0.1.0", + "commands": [ + "reviewmark" + ] } } } \ No newline at end of file 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..5f1c062 --- /dev/null +++ b/.cspell.yaml @@ -0,0 +1,77 @@ +--- +# 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 + - buildmark + - BuildMark + - camelcase + - CodeQL + - copilot + - cspell + - csproj + - dcterms + - DEMA + - 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 + - venv + - versionmark + - VersionMark + - 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 deleted file mode 100644 index 5c613a2..0000000 --- a/.github/agents/code-quality-agent.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -name: Code Quality Agent -description: Ensures code quality through linting and static analysis - responsible for security, maintainability, and correctness ---- - -# Code Quality Agent - ReqStream - -Enforce quality standards through linting, static analysis, and security scanning. - -## When to Invoke This Agent - -Invoke the code-quality-agent for: - -- 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 - -## Responsibilities - -### Primary Responsibility - -Ensure the project is: - -- **Secure**: No security vulnerabilities -- **Maintainable**: Clean, well-formatted, documented code -- **Correct**: Does what it claims to do (requirements met) - -### Quality Gates (ALL Must Pass) - -1. **Build**: Zero warnings (TreatWarningsAsErrors=true) -2. **Linting**: - - markdownlint (`.markdownlint-cli2.jsonc`) - - cspell (`.cspell.json`) - - 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 - -### ReqStream-Specific - -- **XML Docs**: Enforce on ALL members (public/internal/private) -- **Code Style**: Verify `.editorconfig` compliance -- **Test Naming**: Check `ReqStream_*` pattern for self-validation tests - -### Commands to Run - -```bash -# Code formatting -dotnet format --verify-no-changes - -# Build with zero warnings -dotnet build --configuration Release - -# Run validation tests -dotnet run --project src/DemaConsulting.ReqStream \ - --configuration Release --framework net10.0 --no-build -- --validate - -# Requirements enforcement -dotnet reqstream --requirements requirements.yaml \ - --tests "test-results/**/*.trx" --enforce - -# Run all linters -./lint.sh # Linux/macOS -lint.bat # Windows -``` - -## Defer To - -- **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 - -## Don't - -- Disable quality checks to make builds pass -- Ignore security warnings -- Skip enforcement of requirements traceability -- Change functional code without consulting appropriate developer agent diff --git a/.github/agents/code-quality.agent.md b/.github/agents/code-quality.agent.md new file mode 100644 index 0000000..4c15c87 --- /dev/null +++ b/.github/agents/code-quality.agent.md @@ -0,0 +1,216 @@ +--- +name: code-quality +description: Ensures code quality through comprehensive linting and static analysis. +tools: [read, search, edit, execute, github, agent] +user-invocable: true +--- + +# Code Quality Agent + +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 + +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 + +**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. + +### Comprehensive Quality Gate Enforcement + +The project MUST be: + +- **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 + +### Universal 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 +``` + +**Note**: The @code-quality agent is responsible for maintaining the `lint.sh`/`lint.bat` scripts. + +#### 2. Build Quality (Zero Warnings) + +All builds must be configured to treat warnings as errors. +This ensures that compiler warnings are addressed immediately rather than accumulating as technical debt. + +#### 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 +# 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.** + +### Lint Script Maintenance + +When updating tool versions or maintaining linting infrastructure, +modify the lint scripts: + +- **`lint.sh`** - Unix/Linux/macOS comprehensive linting script +- **`lint.bat`** - Windows comprehensive linting script + +**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 +``` + +### 2. Security Gate Validation + +```bash +# CodeQL analysis (automated in GitHub Actions) +codeql database create --language=csharp +codeql database analyze --format=sarif-latest --output=results.sarif + +# Dependency vulnerability scanning +dotnet list package --vulnerable --include-transitive +npm audit --audit-level=moderate # if Node.js dependencies +``` + +### 3. Documentation & Compliance Gates + +```bash +# File review status validation +dotnet reviewmark --definition .reviewmark.yaml --enforce + +# Generate compliance documentation +dotnet buildmark --tools tools.yaml --output docs/build_notes.md +dotnet reqstream --report docs/requirements_doc/requirements.md --justifications docs/requirements_doc/justifications.md +``` + +## 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/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 77% rename from .github/agents/requirements-agent.md rename to .github/agents/requirements.agent.md index f6e0c17..3982e6f 100644 --- a/.github/agents/requirements-agent.md +++ b/.github/agents/requirements.agent.md @@ -1,6 +1,8 @@ --- -name: Requirements Agent -description: Develops requirements and ensures appropriate test coverage - knows which requirements need unit/integration/self-validation tests +name: requirements +description: Develops requirements and ensures appropriate test coverage. +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 71% rename from .github/agents/software-developer.md rename to .github/agents/software-developer.agent.md index 2b0b374..6c4338a 100644 --- a/.github/agents/software-developer.md +++ b/.github/agents/software-developer.agent.md @@ -1,6 +1,8 @@ --- -name: Software Developer -description: Writes production code and self-validation tests - targets design-for-testability and literate programming style +name: software-developer +description: Writes production code and self-validation tests. +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 60% rename from .github/agents/technical-writer.md rename to .github/agents/technical-writer.agent.md index c84bb64..30d2f5b 100644 --- a/.github/agents/technical-writer.md +++ b/.github/agents/technical-writer.agent.md @@ -1,6 +1,8 @@ --- -name: Technical Writer -description: Ensures documentation is accurate and complete - knowledgeable about regulatory documentation and special document types +name: technical-writer +description: Ensures documentation is accurate and complete. +tools: [read, search, edit, execute, github, agent] +user-invocable: true --- # Technical Writer - ReqStream @@ -34,14 +36,15 @@ 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) #### 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 +55,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 83% rename from .github/agents/test-developer.md rename to .github/agents/test-developer.agent.md index 67f58dd..a287b0b 100644 --- a/.github/agents/test-developer.md +++ b/.github/agents/test-developer.agent.md @@ -1,6 +1,8 @@ --- -name: Test Developer -description: Writes unit and integration tests following AAA pattern - clear documentation of what's tested and proved +name: test-developer +description: Writes unit and integration tests. +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/.github/workflows/build.yaml b/.github/workflows/build.yaml index ddebc0f..2b88433 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -463,7 +463,7 @@ jobs: echo "Capturing tool versions..." dotnet versionmark --capture --job-id "build-docs" \ --output "artifacts/versionmark-build-docs.json" -- \ - dotnet git node npm pandoc weasyprint sarifmark sonarmark reqstream buildmark versionmark + dotnet git node npm pandoc weasyprint sarifmark sonarmark reqstream buildmark versionmark reviewmark echo "✓ Tool versions captured" # === CAPTURE OTS SELF-VALIDATION RESULTS === @@ -485,6 +485,9 @@ jobs: - name: Run SonarMark self-validation run: dotnet sonarmark --validate --results artifacts/sonarmark-self-validation.trx + - name: Run ReviewMark self-validation + run: dotnet reviewmark --validate --results artifacts/reviewmark-self-validation.trx + # === GENERATE MARKDOWN REPORTS === # This section generates all markdown reports from various tools and sources. # Downstream projects: Add any additional markdown report generation steps here. @@ -494,16 +497,16 @@ jobs: reqstream --requirements requirements.yaml --tests "artifacts/**/*.trx" - --report docs/requirements/requirements.md - --justifications docs/justifications/justifications.md - --matrix docs/tracematrix/tracematrix.md + --report docs/requirements_doc/requirements.md + --justifications docs/requirements_doc/justifications.md + --matrix docs/requirements_report/trace_matrix.md --enforce - name: Generate CodeQL Quality Report with SarifMark run: > dotnet sarifmark --sarif artifacts/csharp.sarif - --report docs/quality/codeql-quality.md + --report docs/code_quality/codeql-quality.md --heading "ReqStream CodeQL Analysis" --report-depth 1 @@ -511,7 +514,7 @@ jobs: shell: bash run: | echo "=== CodeQL Quality Report ===" - cat docs/quality/codeql-quality.md + cat docs/code_quality/codeql-quality.md - name: Generate SonarCloud Quality Report shell: bash @@ -523,14 +526,37 @@ jobs: --project-key demaconsulting_ReqStream --branch ${{ github.ref_name }} --token "$SONAR_TOKEN" - --report docs/quality/sonar-quality.md + --report docs/code_quality/sonar-quality.md --report-depth 1 - name: Display SonarCloud Quality Report shell: bash run: | echo "=== SonarCloud Quality Report ===" - cat docs/quality/sonar-quality.md + cat docs/code_quality/sonar-quality.md + + - name: Generate Review Plan and Review Report with ReviewMark + shell: bash + # TODO: Add --enforce once reviews branch is populated with review evidence PDFs and index.json + run: > + dotnet reviewmark + --definition .reviewmark.yaml + --plan docs/code_review_plan/plan.md + --plan-depth 1 + --report docs/code_review_report/report.md + --report-depth 1 + + - name: Display Review Plan + shell: bash + run: | + echo "=== Review Plan ===" + cat docs/code_review_plan/plan.md + + - name: Display Review Report + shell: bash + run: | + echo "=== Review Report ===" + cat docs/code_review_report/report.md - name: Generate Build Notes with BuildMark shell: bash @@ -539,20 +565,20 @@ jobs: run: > dotnet buildmark --build-version ${{ inputs.version }} - --report docs/buildnotes.md + --report docs/build_notes.md --report-depth 1 - name: Display Build Notes Report shell: bash run: | echo "=== Build Notes Report ===" - cat docs/buildnotes.md + cat docs/build_notes.md - name: Publish Tool Versions shell: bash run: | echo "Publishing tool versions..." - dotnet versionmark --publish --report docs/buildnotes/versions.md --report-depth 1 \ + dotnet versionmark --publish --report docs/build_notes/versions.md --report-depth 1 \ -- "artifacts/**/versionmark-*.json" echo "✓ Tool versions published" @@ -560,7 +586,7 @@ jobs: shell: bash run: | echo "=== Tool Versions Report ===" - cat docs/buildnotes/versions.md + cat docs/build_notes/versions.md # === GENERATE HTML DOCUMENTS WITH PANDOC === # This section converts markdown documents to HTML using Pandoc. @@ -570,11 +596,11 @@ jobs: shell: bash run: > dotnet pandoc - --defaults docs/buildnotes/definition.yaml + --defaults docs/build_notes/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/buildnotes/buildnotes.html + --output docs/build_notes/buildnotes.html - name: Generate Guide HTML with Pandoc shell: bash @@ -590,41 +616,51 @@ jobs: shell: bash run: > dotnet pandoc - --defaults docs/quality/definition.yaml + --defaults docs/code_quality/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/quality/quality.html + --output docs/code_quality/quality.html - name: Generate Requirements HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/requirements/definition.yaml + --defaults docs/requirements_doc/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/requirements/requirements.html + --output docs/requirements_doc/requirements.html - - name: Generate Requirements Justifications HTML with Pandoc + - name: Generate Trace Matrix HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/justifications/definition.yaml + --defaults docs/requirements_report/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/justifications/justifications.html + --output docs/requirements_report/trace_matrix.html - - name: Generate Trace Matrix HTML with Pandoc + - name: Generate Review Plan HTML with Pandoc + shell: bash + run: > + dotnet pandoc + --defaults docs/code_review_plan/definition.yaml + --filter node_modules/.bin/mermaid-filter.cmd + --metadata version="${{ inputs.version }}" + --metadata date="$(date +'%Y-%m-%d')" + --output docs/code_review_plan/plan.html + + - name: Generate Review Report HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/tracematrix/definition.yaml + --defaults docs/code_review_report/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/tracematrix/tracematrix.html + --output docs/code_review_report/report.html # === GENERATE PDF DOCUMENTS WITH WEASYPRINT === # This section converts HTML documents to PDF using Weasyprint. @@ -634,7 +670,7 @@ jobs: run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/buildnotes/buildnotes.html + docs/build_notes/buildnotes.html "docs/ReqStream Build Notes.pdf" - name: Generate Guide PDF with Weasyprint @@ -648,29 +684,36 @@ jobs: run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/quality/quality.html + docs/code_quality/quality.html "docs/ReqStream Code Quality.pdf" - name: Generate Requirements PDF with Weasyprint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/requirements/requirements.html + docs/requirements_doc/requirements.html "docs/ReqStream Requirements.pdf" - - name: Generate Requirements Justifications PDF with Weasyprint + - name: Generate Trace Matrix PDF with Weasyprint + run: > + dotnet weasyprint + --pdf-variant pdf/a-3u + docs/requirements_report/trace_matrix.html + "docs/ReqStream Trace Matrix.pdf" + + - name: Generate Review Plan PDF with Weasyprint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/justifications/justifications.html - "docs/ReqStream Requirements Justifications.pdf" + docs/code_review_plan/plan.html + "docs/ReqStream Review Plan.pdf" - - name: Generate Trace Matrix PDF with Weasyprint + - name: Generate Review Report PDF with Weasyprint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/tracematrix/tracematrix.html - "docs/ReqStream Trace Matrix.pdf" + docs/code_review_report/report.html + "docs/ReqStream Review Report.pdf" # === UPLOAD ARTIFACTS === # This section uploads all generated documentation artifacts. @@ -682,4 +725,4 @@ jobs: name: documents path: | docs/*.pdf - docs/buildnotes.md + docs/build_notes.md diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 9a81642..ff33f49 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -63,18 +63,13 @@ jobs: name: documents path: artifacts - - name: Move buildnotes.md to root - run: | - set -e - mv artifacts/buildnotes.md buildnotes.md - - name: Create GitHub Release if: inputs.publish == 'release' || inputs.publish == 'publish' uses: ncipollo/release-action@v1 with: tag: ${{ inputs.version }} - artifacts: artifacts/* - bodyFile: buildnotes.md + artifacts: artifacts/** + bodyFile: artifacts/docs/build_notes.md generateReleaseNotes: false - name: Publish to NuGet.org diff --git a/.gitignore b/.gitignore index 1e5419d..48dc886 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,121 +33,73 @@ 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 !docs/template/** -docs/requirements/requirements.md -docs/justifications/justifications.md -docs/tracematrix/tracematrix.md -docs/quality/codeql-quality.md -docs/quality/sonar-quality.md -docs/buildnotes.md -docs/buildnotes/versions.md +docs/requirements_doc/requirements.md +docs/requirements_doc/justifications.md +docs/requirements_report/trace_matrix.md +docs/code_quality/codeql-quality.md +docs/code_quality/sonar-quality.md +docs/code_review_plan/plan.md +docs/code_review_report/report.md +docs/build_notes.md +docs/build_notes/versions.md # Test results TestResults/ diff --git a/.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..04f1f80 --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,47 @@ +--- +# 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 + + # Require ATX-style headers (# Header) instead of Setext-style + MD003: + style: atx + + # Set consistent indentation for nested lists + MD007: + indent: 2 + + # Allow longer lines for URLs and technical content + MD013: + line_length: 120 + + # Allow multiple top-level headers per document + MD025: false + + # Allow inline HTML for enhanced documentation + 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/.reviewmark.yaml b/.reviewmark.yaml new file mode 100644 index 0000000..dfa43f2 --- /dev/null +++ b/.reviewmark.yaml @@ -0,0 +1,82 @@ +--- +# 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: + - "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" + - "test/**/ValidationTests.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" + - "test/**/RequirementsReadTests.cs" + - "test/**/RequirementsExportTests.cs" + + - 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" + - "docs/reqstream/ots-reviewmark.yaml" 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 446fdce..6c6c4fb 100644 --- a/.yamllint.yaml +++ b/.yamllint.yaml @@ -1,14 +1,31 @@ --- -# 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 +# 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: 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 07447b4..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 @@ -32,7 +34,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 @@ -108,7 +120,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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 459c02c..1de683a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,49 +1,57 @@ # 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.) +- 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 @@ -57,80 +65,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 + - 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 +} +``` -- 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%) +Note the spaces after `///` for proper indentation in summary blocks. -### Commit Messages +## Testing Guidelines -Write clear, descriptive commit messages: +### Test Framework -- Use the imperative mood ("Add feature" not "Added feature") -- Keep the first line under 72 characters -- Add details in the body if needed +We use MSTest v4 for unit and integration tests. -Example: +### Test Naming Convention -```text -Add validation for requirement IDs +Use the pattern: `ClassName_MethodUnderTest_Scenario_ExpectedBehavior` -- Ensures requirement IDs are unique -- Adds tests for duplicate ID detection -- Updates error messages for clarity -``` +Examples: -## Quality Checks +- `Program_Main_NoArguments_ReturnsSuccess` +- `Context_Create_WithInvalidFlag_ThrowsArgumentException` +- `Validation_Run_AllTests_ReturnsSuccess` -Before submitting a pull request, ensure your code passes all quality checks: +### Writing Tests -### Build and Test - -```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,68 +173,127 @@ dotnet run --project src/DemaConsulting.ReqStream \ --configuration Release --framework net10.0 --no-build -- --validate ``` -### Linting +## Documentation + +### Markdown Guidelines -The CI pipeline runs the following checks: +All markdown files must follow these rules (enforced by markdownlint): -- **Markdown linting**: Checks markdown file formatting -- **Spell checking**: Validates spelling in markdown and C# files -- **YAML linting**: Validates YAML file structure +- 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 -You can run these locally if you have the tools installed: +### 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. + +## Quality Checks + +Before submitting a pull request, ensure all quality checks pass: + +### 1. Build, Test, and Validate ```bash -# Markdown linting -markdownlint-cli2 "**/*.md" +# Build the project +dotnet build --configuration Release -# Spell checking -cspell "**/*.md" "**/*.cs" +# Run unit tests +dotnet test --configuration Release -# YAML linting -yamllint . +# Run self-validation tests +dotnet run --project src/DemaConsulting.ReqStream --configuration Release --framework net10.0 --no-build -- --validate ``` -## Pull Request Process +All tests must pass with zero warnings. + +### 2. Linting -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 +```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) ``` -## Questions? +### 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 @@ -224,6 +301,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/docs/build_notes/definition.yaml b/docs/build_notes/definition.yaml new file mode 100644 index 0000000..4aa8572 --- /dev/null +++ b/docs/build_notes/definition.yaml @@ -0,0 +1,16 @@ +--- +resource-path: + - docs/build_notes + - docs/template + +input-files: + - docs/build_notes/title.txt + - docs/build_notes/introduction.md + - docs/build_notes.md + - docs/build_notes/versions.md + +template: template.html + +table-of-contents: true + +number-sections: true diff --git a/docs/buildnotes/introduction.md b/docs/build_notes/introduction.md similarity index 100% rename from docs/buildnotes/introduction.md rename to docs/build_notes/introduction.md diff --git a/docs/buildnotes/title.txt b/docs/build_notes/title.txt similarity index 100% rename from docs/buildnotes/title.txt rename to docs/build_notes/title.txt diff --git a/docs/buildnotes/definition.yaml b/docs/buildnotes/definition.yaml deleted file mode 100644 index 7eb0c4c..0000000 --- a/docs/buildnotes/definition.yaml +++ /dev/null @@ -1,16 +0,0 @@ ---- -resource-path: - - docs/buildnotes - - docs/template - -input-files: - - docs/buildnotes/title.txt - - docs/buildnotes/introduction.md - - docs/buildnotes.md - - docs/buildnotes/versions.md - -template: template.html - -table-of-contents: true - -number-sections: true diff --git a/docs/code_quality/definition.yaml b/docs/code_quality/definition.yaml new file mode 100644 index 0000000..68c58f2 --- /dev/null +++ b/docs/code_quality/definition.yaml @@ -0,0 +1,12 @@ +--- +resource-path: + - docs/code_quality + - docs/template +input-files: + - docs/code_quality/title.txt + - docs/code_quality/introduction.md + - docs/code_quality/codeql-quality.md + - docs/code_quality/sonar-quality.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/quality/introduction.md b/docs/code_quality/introduction.md similarity index 100% rename from docs/quality/introduction.md rename to docs/code_quality/introduction.md diff --git a/docs/quality/title.txt b/docs/code_quality/title.txt similarity index 100% rename from docs/quality/title.txt rename to docs/code_quality/title.txt diff --git a/docs/code_review_plan/definition.yaml b/docs/code_review_plan/definition.yaml new file mode 100644 index 0000000..3a24f0b --- /dev/null +++ b/docs/code_review_plan/definition.yaml @@ -0,0 +1,11 @@ +--- +resource-path: + - docs/code_review_plan + - docs/template +input-files: + - docs/code_review_plan/title.txt + - docs/code_review_plan/introduction.md + - docs/code_review_plan/plan.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/code_review_plan/introduction.md b/docs/code_review_plan/introduction.md new file mode 100644 index 0000000..95c58f8 --- /dev/null +++ b/docs/code_review_plan/introduction.md @@ -0,0 +1,32 @@ +# Introduction + +This document contains the review plan for the ReqStream project. + +## Purpose + +This review plan provides a comprehensive overview of all files requiring formal review +in the ReqStream project. It identifies which review-sets cover which files and serves +as evidence that every file requiring review is covered by at least one named review-set. + +## Scope + +This review plan covers: + +- C# source code files requiring formal review +- YAML configuration and requirements files requiring formal review +- Mapping of reviewed files to named review-sets + +## Generation Source + +This plan is automatically generated by the ReviewMark tool, analyzing the +`.reviewmark.yaml` configuration and the review evidence store. It serves as evidence +that every file requiring review is covered by a current, valid review. + +## Audience + +This document is intended for: + +- Software developers working on ReqStream +- Quality assurance teams validating review coverage +- Project stakeholders reviewing compliance status +- Auditors verifying that all required files have been reviewed diff --git a/docs/code_review_plan/title.txt b/docs/code_review_plan/title.txt new file mode 100644 index 0000000..50bf13b --- /dev/null +++ b/docs/code_review_plan/title.txt @@ -0,0 +1,13 @@ +--- +title: ReqStream Review Plan +subtitle: File Review Plan for the ReqStream Tool +author: DEMA Consulting +description: File Review Plan for the ReqStream Tool +lang: en-US +keywords: + - ReqStream + - Review Plan + - File Reviews + - .NET + - Tool +--- diff --git a/docs/code_review_report/definition.yaml b/docs/code_review_report/definition.yaml new file mode 100644 index 0000000..6498e6c --- /dev/null +++ b/docs/code_review_report/definition.yaml @@ -0,0 +1,11 @@ +--- +resource-path: + - docs/code_review_report + - docs/template +input-files: + - docs/code_review_report/title.txt + - docs/code_review_report/introduction.md + - docs/code_review_report/report.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/code_review_report/introduction.md b/docs/code_review_report/introduction.md new file mode 100644 index 0000000..6242755 --- /dev/null +++ b/docs/code_review_report/introduction.md @@ -0,0 +1,32 @@ +# Introduction + +This document contains the review report for the ReqStream project. + +## Purpose + +This review report provides evidence that each review-set is current — the review +evidence matches the current file fingerprints. It confirms that all formal reviews +conducted for ReqStream remain valid for the current state of the reviewed files. + +## Scope + +This review report covers: + +- Current review-set status (current, stale, or missing) +- File fingerprints and review evidence matching +- Review coverage verification + +## Generation Source + +This report is automatically generated by the ReviewMark tool, comparing the current +file fingerprints against the review evidence store. It serves as evidence that all +review-sets are current and no reviewed file has changed since its review was conducted. + +## Audience + +This document is intended for: + +- Software developers working on ReqStream +- Quality assurance teams validating review currency +- Project stakeholders reviewing compliance status +- Auditors verifying that all reviews remain valid for the current release diff --git a/docs/code_review_report/title.txt b/docs/code_review_report/title.txt new file mode 100644 index 0000000..5c4d46a --- /dev/null +++ b/docs/code_review_report/title.txt @@ -0,0 +1,13 @@ +--- +title: ReqStream Review Report +subtitle: File Review Report for the ReqStream Tool +author: DEMA Consulting +description: File Review Report for the ReqStream Tool +lang: en-US +keywords: + - ReqStream + - Review Report + - File Reviews + - .NET + - Tool +--- diff --git a/docs/justifications/definition.yaml b/docs/justifications/definition.yaml deleted file mode 100644 index d0bbbee..0000000 --- a/docs/justifications/definition.yaml +++ /dev/null @@ -1,11 +0,0 @@ ---- -resource-path: - - docs/justifications - - docs/template -input-files: - - docs/justifications/title.txt - - docs/justifications/introduction.md - - docs/justifications/justifications.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/justifications/introduction.md b/docs/justifications/introduction.md deleted file mode 100644 index 395135e..0000000 --- a/docs/justifications/introduction.md +++ /dev/null @@ -1,42 +0,0 @@ -# Introduction - -This document provides the rationale and justification for each requirement in the ReqStream tool specification. -Understanding why requirements exist helps developers, stakeholders, and future maintainers make informed decisions -about the tool's design and evolution. - -## Purpose - -The purpose of this document is to explain the reasoning behind each requirement in the ReqStream tool. Each -justification provides context about: - -- Why the requirement is necessary -- What problem it solves -- How it benefits users or the system -- Any relevant design considerations - -## Scope - -This document covers justifications for: - -- Command-line interface requirements -- Requirements file processing capabilities -- Test integration features -- Reporting and export functionality -- Platform and runtime support -- Validation and enforcement features - -## How to Use This Document - -Each requirement is presented with: - -- **Requirement ID and Title**: The unique identifier and description from the requirements specification -- **Justification**: A clear explanation of why the requirement exists and its value to the system - -This document should be read alongside the ReqStream Requirements Specification to gain a complete understanding -of both what the tool must do (requirements) and why it must do it (justifications). - -## References - -- ReqStream Requirements: Provides the complete requirements specification -- ReqStream User Guide: Provides detailed usage instructions and examples -- ReqStream Repository: diff --git a/docs/justifications/title.txt b/docs/justifications/title.txt deleted file mode 100644 index 0308f5c..0000000 --- a/docs/justifications/title.txt +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: ReqStream Requirements Justifications -subtitle: Rationale and Context for ReqStream Requirements -author: DEMA Consulting -description: Requirements Justifications for the ReqStream Tool -lang: en-US -keywords: - - ReqStream - - Requirements - - Justifications - - Rationale - - .NET - - YAML - - Command-Line Tool ---- diff --git a/docs/quality/definition.yaml b/docs/quality/definition.yaml deleted file mode 100644 index 65420a4..0000000 --- a/docs/quality/definition.yaml +++ /dev/null @@ -1,16 +0,0 @@ ---- -resource-path: - - docs/quality - - docs/template - -input-files: - - docs/quality/title.txt - - docs/quality/introduction.md - - docs/quality/codeql-quality.md - - docs/quality/sonar-quality.md - -template: template.html - -table-of-contents: true - -number-sections: true diff --git a/docs/reqstream/ots-buildmark.yaml b/docs/reqstream/ots-buildmark.yaml new file mode 100644 index 0000000..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-reviewmark.yaml b/docs/reqstream/ots-reviewmark.yaml new file mode 100644 index 0000000..e631441 --- /dev/null +++ b/docs/reqstream/ots-reviewmark.yaml @@ -0,0 +1,21 @@ +--- +# ReviewMark OTS Software Requirements +# +# Requirements for the ReviewMark file review tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: ReviewMark Requirements + requirements: + - id: ReqStream-OTS-ReviewMark + title: ReviewMark shall generate a review plan and review report from the review configuration. + justification: | + DemaConsulting.ReviewMark reads the .reviewmark.yaml configuration and the review + evidence store to produce a review plan and review report documenting file review + coverage and currency. It runs in the same CI pipeline that produces the TRX test + results, so a successful pipeline run is evidence that ReviewMark executed without error. + tags: [ots] + tests: + - ReviewMark_ReviewPlanGeneration + - ReviewMark_ReviewReportGeneration diff --git a/docs/reqstream/ots-sarifmark.yaml b/docs/reqstream/ots-sarifmark.yaml new file mode 100644 index 0000000..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..2f68a8b --- /dev/null +++ b/docs/reqstream/platform-requirements.yaml @@ -0,0 +1,110 @@ +# 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 + 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..a6e5896 --- /dev/null +++ b/docs/reqstream/unit-context.yaml @@ -0,0 +1,94 @@ +--- +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-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: | + 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..1fbd101 --- /dev/null +++ b/docs/reqstream/unit-program.yaml @@ -0,0 +1,62 @@ +--- +sections: + - title: ReqStream Requirements + 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 new file mode 100644 index 0000000..0f78458 --- /dev/null +++ b/docs/reqstream/unit-requirements.yaml @@ -0,0 +1,114 @@ +--- +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-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..52e7f1f --- /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 + - TraceMatrix_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..4631b1a --- /dev/null +++ b/docs/reqstream/unit-validation.yaml @@ -0,0 +1,36 @@ +--- +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 + - Validation_Run_WithSilentContext_CompletesSuccessfully + - Validation_Run_WithTrxResultsFile_WritesTrxFile + - Validation_Run_WithXmlResultsFile_WritesXmlFile + + - 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/docs/requirements/definition.yaml b/docs/requirements/definition.yaml deleted file mode 100644 index a0f3371..0000000 --- a/docs/requirements/definition.yaml +++ /dev/null @@ -1,11 +0,0 @@ ---- -resource-path: - - docs/requirements - - docs/template -input-files: - - docs/requirements/title.txt - - docs/requirements/introduction.md - - docs/requirements/requirements.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/requirements_doc/definition.yaml b/docs/requirements_doc/definition.yaml new file mode 100644 index 0000000..0f4ccd2 --- /dev/null +++ b/docs/requirements_doc/definition.yaml @@ -0,0 +1,12 @@ +--- +resource-path: + - docs/requirements_doc + - docs/template +input-files: + - docs/requirements_doc/title.txt + - docs/requirements_doc/introduction.md + - docs/requirements_doc/requirements.md + - docs/requirements_doc/justifications.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/requirements/introduction.md b/docs/requirements_doc/introduction.md similarity index 100% rename from docs/requirements/introduction.md rename to docs/requirements_doc/introduction.md diff --git a/docs/requirements/title.txt b/docs/requirements_doc/title.txt similarity index 100% rename from docs/requirements/title.txt rename to docs/requirements_doc/title.txt diff --git a/docs/requirements_report/definition.yaml b/docs/requirements_report/definition.yaml new file mode 100644 index 0000000..918a645 --- /dev/null +++ b/docs/requirements_report/definition.yaml @@ -0,0 +1,11 @@ +--- +resource-path: + - docs/requirements_report + - docs/template +input-files: + - docs/requirements_report/title.txt + - docs/requirements_report/introduction.md + - docs/requirements_report/trace_matrix.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/requirements_report/introduction.md b/docs/requirements_report/introduction.md new file mode 100644 index 0000000..82a8bc1 --- /dev/null +++ b/docs/requirements_report/introduction.md @@ -0,0 +1,27 @@ +# Introduction + +This document contains the requirements traceability matrix for the ReqStream project. + +## Purpose + +The trace matrix provides traceability between requirements and test cases, ensuring that +all requirements are validated through appropriate testing. This demonstrates that the +ReqStream tool meets its specified requirements. + +## Scope + +This traceability matrix covers: + +- Mapping of requirements to test cases +- Test execution results linked to requirements +- Validation of requirement coverage +- Platform-specific test execution + +## Audience + +This document is intended for: + +- Software developers working on ReqStream +- Quality assurance teams validating requirements coverage +- Project stakeholders reviewing test coverage +- Auditors verifying requirements traceability diff --git a/docs/tracematrix/title.txt b/docs/requirements_report/title.txt similarity index 50% rename from docs/tracematrix/title.txt rename to docs/requirements_report/title.txt index 312a153..c555dc4 100644 --- a/docs/tracematrix/title.txt +++ b/docs/requirements_report/title.txt @@ -1,14 +1,14 @@ --- title: ReqStream Trace Matrix -subtitle: Test Traceability Matrix for the ReqStream Tool +subtitle: Requirements Traceability Matrix for the ReqStream Tool author: DEMA Consulting -description: Test Traceability Matrix for the ReqStream Tool +description: Requirements Traceability Matrix for the ReqStream Tool lang: en-US keywords: - ReqStream - Trace Matrix - Traceability + - Requirements - Testing - .NET - - Command-Line Tool --- diff --git a/docs/tracematrix/definition.yaml b/docs/tracematrix/definition.yaml deleted file mode 100644 index ba93d57..0000000 --- a/docs/tracematrix/definition.yaml +++ /dev/null @@ -1,11 +0,0 @@ ---- -resource-path: - - docs/tracematrix - - docs/template -input-files: - - docs/tracematrix/title.txt - - docs/tracematrix/introduction.md - - docs/tracematrix/tracematrix.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/tracematrix/introduction.md b/docs/tracematrix/introduction.md deleted file mode 100644 index fe25ad2..0000000 --- a/docs/tracematrix/introduction.md +++ /dev/null @@ -1,37 +0,0 @@ -# Introduction - -This document provides a traceability matrix that maps ReqStream requirements to their associated test cases. -This matrix ensures that each requirement is adequately tested and verified. - -## Purpose - -The purpose of this trace matrix is to: - -- Demonstrate test coverage for all requirements -- Provide traceability between requirements and tests -- Support verification and validation activities -- Facilitate impact analysis when requirements change - -## Scope - -This document covers the traceability between: - -- ReqStream requirements defined in the requirements specification -- Test cases implemented in the ReqStream test suite - -## Matrix Organization - -The trace matrix is organized by requirement, showing: - -- Requirement identifier and title -- Associated test cases that verify the requirement -- Test execution status - -## How to Use This Document - -Use this trace matrix to: - -- Verify that all requirements have associated tests -- Identify which tests verify each requirement -- Assess test coverage across the requirement set -- Plan testing activities when requirements change 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 diff --git a/requirements.yaml b/requirements.yaml index a05d146..4200c05 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -1,638 +1,15 @@ -# Requirements Testing Strategy -# -# This project uses three categories of tests to verify requirements: -# -# 1. Unit Tests - Run locally via "dotnet test" -# 2. Self-Validation Tests - Run locally via "--validate" -# 3. Platform Tests - Run via CI/CD across OS/runtime matrix -# -# NOTE: Running "reqstream --enforce" with only local test results (unit tests -# and local self-validation) is expected to show some unsatisfied requirements. -# Platform-specific requirements require test results from CI/CD runs across -# the full OS and runtime matrix. -# -# Test links can include a source filter prefix (e.g. "windows@", "ubuntu@", "net8.0@", -# "dotnet8.x@") to restrict which test results count as evidence for a requirement. This -# is critical for platform and framework requirements - removing these filters invalidates -# the evidence-based proof. -# -# Source filter prefixes: -# windows@TestName - proves the test passed on a Windows platform -# ubuntu@TestName - proves the test passed on a Linux (Ubuntu) platform -# macos@TestName - proves the test passed on a macOS platform -# net8.0@TestName - proves the test passed under the .NET 8 target framework -# net9.0@TestName - proves the test passed under the .NET 9 target framework -# net10.0@TestName - proves the test passed under the .NET 10 target framework -# dotnet8.x@TestName - proves the self-validation test ran with .NET 8.x runtime -# dotnet9.x@TestName - proves the self-validation test ran with .NET 9.x runtime -# dotnet10.x@TestName - proves the self-validation test ran with .NET 10.x runtime -# --- -sections: - - title: 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 + - docs/reqstream/ots-reviewmark.yaml diff --git a/test/DemaConsulting.ReqStream.Tests/ValidationTests.cs b/test/DemaConsulting.ReqStream.Tests/ValidationTests.cs new file mode 100644 index 0000000..4c04f9f --- /dev/null +++ b/test/DemaConsulting.ReqStream.Tests/ValidationTests.cs @@ -0,0 +1,162 @@ +// 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("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); + } +}