diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index b687954..e320391 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -33,7 +33,7 @@ ] }, "demaconsulting.reqstream": { - "version": "1.10.0", + "version": "1.11.0", "commands": [ "reqstream" ] diff --git a/docs/reqstream/quality.yaml b/docs/reqstream/quality.yaml new file mode 100644 index 0000000..1dea234 --- /dev/null +++ b/docs/reqstream/quality.yaml @@ -0,0 +1,176 @@ +--- +# Repository quality requirements +# +# These requirements express repository/process-level quality outcomes that are +# satisfied through the CI pipeline's use of off-the-shelf compliance and +# documentation tools. They are distinct from the VersionMark product requirements +# in version-mark.yaml: each requirement here states WHAT quality outcome the +# repository needs (e.g. "changes are peer reviewed"), never HOW that outcome is +# currently achieved. The OTS tool that currently satisfies each outcome is +# recorded only as a `children` link, never in the requirement title or +# justification, so that satisfying the outcome by different or additional means +# in the future would not require rewriting the requirement itself. +sections: + - title: Repository Quality Requirements + requirements: + - id: VersionMark-Quality-BuildIntegrity + title: >- + Every release shall carry a documented record of the CI build that + produced it, captured automatically from pipeline metadata. + justification: | + Regulated and quality-conscious consumers of VersionMark require assurance that + each release artifact was produced by a specific, auditable build rather than + an ad-hoc or undocumented process. Capturing build provenance (workflow run + identity, commit, timestamp) automatically as part of the CI pipeline, rather + than relying on manual record-keeping, ensures the record is always present, + accurate, and resistant to after-the-fact tampering. + This requirement is satisfied by its children: it is a non-atomic (grouping) + requirement, and verification evidence is carried by each atomic child + requirement's tests. + tags: [quality] + children: + - VersionMark-OTS-BuildMark + tests: + - BuildMark_MarkdownReportGeneration + + - id: VersionMark-Quality-StaticAnalysis + title: >- + Code shall be automatically scanned for defects, vulnerabilities, and + quality regressions before merge. + justification: | + Manual code review alone cannot reliably catch every security vulnerability, + code smell, or quality regression introduced by a change. Automated static + analysis on every pull request, with results captured as auditable reports, + provides continuous, objective quality and security assurance that scales + with the size of the codebase and does not depend solely on reviewer + attentiveness. + This requirement is satisfied by its children: it is a non-atomic (grouping) + requirement, and verification evidence is carried by each atomic child + requirement's tests. + tags: [quality] + children: + - VersionMark-OTS-SarifMark + - VersionMark-OTS-SonarMark + tests: + - SarifMark_SarifReading + - SarifMark_MarkdownReportGeneration + - SonarMark_QualityGateRetrieval + - SonarMark_IssuesRetrieval + + - id: VersionMark-Quality-PeerReview + title: >- + Every change shall receive documented, enforced peer review evidence + before merge. + justification: | + Peer review is a core defense against defects and unintended behavior + reaching production, but review activity that is not tracked cannot be + audited or enforced. Generating a review plan identifying the reviews + required for a change, and a review report documenting the reviews actually + completed, provides objective, auditable evidence that the review process + was followed, supporting compliance and quality assurance activities. + This requirement is satisfied by its children: it is a non-atomic (grouping) + requirement, and verification evidence is carried by each atomic child + requirement's tests. + tags: [quality] + children: + - VersionMark-OTS-ReviewMark-PlanGeneration + - VersionMark-OTS-ReviewMark-ReportGeneration + tests: + - ReviewMark_ReviewPlanGeneration + - ReviewMark_ReviewReportGeneration + + - id: VersionMark-Quality-DocumentationGeneration + title: >- + Repository documentation shall be generated in reviewable and + distributable formats and validated before release. + justification: | + Design, verification, review, and user-guide documentation authored in + Markdown must be converted into distributable formats (HTML for review, + PDF for archival and distribution) as part of the release pipeline, and + each generated document must be validated to confirm it exists, is + well-formed, and contains the expected content, so that a broken + conversion step cannot silently ship incomplete or corrupt compliance + documentation. + This requirement is satisfied by its children: it is a non-atomic (grouping) + requirement, and verification evidence is carried by each atomic child + requirement's tests. + tags: [quality] + children: + - VersionMark-OTS-Pandoc + - VersionMark-OTS-WeasyPrint + - VersionMark-OTS-FileAssert + tests: + - Pandoc_BuildNotesHtml + - Pandoc_CodeQualityHtml + - WeasyPrint_BuildNotesPdf + - WeasyPrint_CodeQualityPdf + - FileAssert_VersionDisplay + - FileAssert_HelpDisplay + + - id: VersionMark-Quality-TestInfrastructure + title: >- + The project's own developer test suite shall execute automatically + and report results in every CI run. + justification: | + Requirements traceability depends on evidence that tests actually executed + and passed; that evidence has no value unless the test framework reliably + discovers, runs, and reports every test method on every CI run, across all + supported platforms and .NET versions, without manual intervention. + This requirement is satisfied by its children: it is a non-atomic (grouping) + requirement, and verification evidence is carried by each atomic child + requirement's tests. + tags: [quality] + children: + - VersionMark-OTS-xUnit + tests: + - Context_Create_NoArguments_ReturnsDefaultContext + - Context_Create_VersionFlag_SetsVersionTrue + - Context_Create_HelpFlag_SetsHelpTrue + - Context_Create_SilentFlag_SetsSilentTrue + - Context_Create_ValidateFlag_SetsValidateTrue + - Context_Create_ResultsFlag_SetsResultsFile + - Context_Create_LogFlag_OpensLogFile + - Context_Create_UnknownArgument_ThrowsArgumentException + - Context_Create_ShortVersionFlag_SetsVersionTrue + + - id: VersionMark-Quality-RequirementsTraceability + title: >- + Every requirement shall be linked to passing tests and enforced as part + of the release pipeline. + justification: | + Requirements that are not linked to verifying tests, or whose tests are not + checked as part of the pipeline, provide no real assurance that the software + behaves as documented. Automatically enforcing requirements-to-test + traceability on every CI run ensures untested or orphaned requirements are + caught before release rather than discovered later. + This requirement is satisfied by its children: it is a non-atomic (grouping) + requirement, and verification evidence is carried by each atomic child + requirement's tests. + tags: [quality] + children: + - VersionMark-OTS-ReqStream + tests: + - ReqStream_EnforcementMode + + - id: VersionMark-Quality-ArchitectureTraceability + title: >- + The project's software structure shall be modeled, validated, and + rendered independent of source code, so its architecture can be + queried and reviewed without reading implementation. + justification: | + Reviewers, auditors, and automated agents need to understand system + structure and responsibilities without reading through source code line by + line. Maintaining an explicit architecture model that is automatically + validated for structural correctness and rendered as diagrams embedded in + design documentation ensures the documented architecture remains + internally consistent and stays usable as a standalone reference. + This requirement is satisfied by its children: it is a non-atomic (grouping) + requirement, and verification evidence is carried by each atomic child + requirement's tests. + tags: [quality] + children: + - VersionMark-OTS-SysML2Tools-Lint + - VersionMark-OTS-SysML2Tools-Render + tests: + - SysML2Tools_LintSelfTest + - SysML2Tools_RenderSvgSelfTest diff --git a/docs/reqstream/version-mark.yaml b/docs/reqstream/version-mark.yaml index 5ac9fd5..9af064f 100644 --- a/docs/reqstream/version-mark.yaml +++ b/docs/reqstream/version-mark.yaml @@ -8,6 +8,7 @@ sections: The primary purpose of VersionMark is to record which tool versions were present in each CI/CD job so that version differences across environments can be detected and reported. + tags: [system] children: - VersionMark-Capture-Capture - VersionMark-Capture-JobId @@ -23,6 +24,7 @@ sections: - VersionMark-Capture-ConfigError - VersionMark-Capture-CommandFailure - VersionMark-VersionMarkConfig-FindVersions + - VersionMark-Program-RunCapture tests: - IntegrationTest_CaptureCommand_CapturesToolVersions @@ -33,6 +35,7 @@ sections: Teams need a human-readable summary of tool versions across all jobs. Publishing to markdown enables the report to be included in release documentation and artifact archives. + tags: [system] children: - VersionMark-Publish-Publish - VersionMark-Publish-Report @@ -43,6 +46,7 @@ sections: - VersionMark-Publish-ConflictReport - VersionMark-Publish-ConflictDisplay - VersionMark-Publish-FileError + - VersionMark-Program-RunPublish tests: - VersionMark_PublishCommand_GeneratesMarkdownReport @@ -53,6 +57,7 @@ sections: Detecting configuration errors early, before a CI/CD run proceeds, reduces wasted build time and provides precise error locations so users can fix problems quickly. + tags: [system] children: - VersionMark-Load-FileExistence - VersionMark-Load-YamlParsing @@ -72,6 +77,10 @@ sections: - VersionMark-Load-VersionMarkLoadResult-Bundle - VersionMark-Load-VersionMarkLoadResult-ErrorRouting - VersionMark-Load-VersionMarkLoadResult-WarnRouting + - VersionMark-Load-LintIssue-Fields + - VersionMark-Load-LintIssue-Format + - VersionMark-CommandLine-Lint + - VersionMark-Program-RunLint tests: - IntegrationTest_LintFlag_ValidConfig_ReturnsSuccess - IntegrationTest_LintFlag_InvalidConfig_ReturnsError @@ -82,11 +91,51 @@ sections: A built-in self-validation suite lets operators confirm that the installed tool is functioning correctly in the deployment environment without requiring external fixtures or test data. + tags: [system] children: - VersionMark-Validate-Capture - VersionMark-Validate-Publish - VersionMark-Validate-LintValid - VersionMark-Validate-LintInvalid - VersionMark-Validate-Results + - VersionMark-CommandLine-Validate + - VersionMark-CommandLine-Results + - VersionMark-OTS-TestResults tests: - IntegrationTest_ValidateFlag_RunsValidation + + - id: VersionMark-System-CommandLine + title: >- + The tool shall provide a consistent command-line interface across all + invocations, including flags to display version and help information, + suppress console output, write a log file, and report errors for + unrecognized arguments. + justification: | + Every DEMA Consulting DotNet Tool exposes the same baseline command-line + conventions so users and CI/CD scripts can rely on predictable behavior + for version display, usage help, output verbosity, logging, and error + reporting regardless of which specific capture, publish, or lint + operation is invoked. + tags: [system] + children: + - VersionMark-CommandLine-Context + - VersionMark-CommandLine-Version + - VersionMark-CommandLine-Help + - VersionMark-CommandLine-Silent + - VersionMark-CommandLine-Log + - VersionMark-CommandLine-ErrorOutput + - VersionMark-CommandLine-InvalidArgs + - VersionMark-CommandLine-ExitCode + - VersionMark-Program-Version + - VersionMark-Program-Dispatch + - VersionMark-Context-Create + - VersionMark-Context-WriteLine + - VersionMark-Context-WriteError + - VersionMark-Context-WriteErrorLog + - VersionMark-Context-WriteErrorExitCode + tests: + - Cli_Run_VersionFlag_ExitsCleanly + - Cli_Run_HelpFlag_DisplaysUsageInformation + - Cli_Run_SilentWithVersionFlag_SuppressesOutput + - Cli_Run_LogFlag_WritesOutputToLogFile + - Cli_Run_InvalidArgs_ThrowsArgumentException diff --git a/docs/reqstream/version-mark/capture.yaml b/docs/reqstream/version-mark/capture.yaml index 64f6e88..4c754be 100644 --- a/docs/reqstream/version-mark/capture.yaml +++ b/docs/reqstream/version-mark/capture.yaml @@ -46,6 +46,8 @@ sections: enabling integration with existing workflows and file structures. tags: - capture + children: + - VersionMark-Utilities-SafePath tests: - Capture_Run_NoToolFilter_CapturesAllConfiguredTools @@ -90,6 +92,14 @@ sections: capture and how to capture them. tags: - capture + children: + - VersionMark-Configuration-YamlConfig + - VersionMark-Configuration-ToolDefinition + - VersionMark-Configuration-OsCommandOverride + - VersionMark-Configuration-OsRegexOverride + - VersionMark-Configuration-ValidateTools + - VersionMark-Configuration-ReadError + - VersionMark-Configuration-ParseError tests: - Capture_Config_ReadFromFile_LoadsToolDefinitions @@ -114,6 +124,7 @@ sections: - capture children: - VersionMark-VersionInfo-Save + - VersionMark-VersionInfo-WriteError tests: - Capture_SaveAndLoad_PreservesAllVersionData - Capture_MultipleCaptures_EachFileHasDistinctJobId diff --git a/docs/reqstream/version-mark/configuration.yaml b/docs/reqstream/version-mark/configuration.yaml index 962c1bf..ce1fe72 100644 --- a/docs/reqstream/version-mark/configuration.yaml +++ b/docs/reqstream/version-mark/configuration.yaml @@ -14,6 +14,7 @@ sections: children: - VersionMark-VersionMarkConfig-ReadFromFile - VersionMark-VersionMarkConfig-Load + - VersionMark-OTS-YamlDotNet tests: - Configuration_ReadFromFile_MultipleTools_AllToolsAccessible diff --git a/docs/reqstream/version-mark/platform-requirements.yaml b/docs/reqstream/version-mark/platform-requirements.yaml index 5243ce0..7d2a1cb 100644 --- a/docs/reqstream/version-mark/platform-requirements.yaml +++ b/docs/reqstream/version-mark/platform-requirements.yaml @@ -10,6 +10,7 @@ sections: DEMA Consulting tools must support Windows as a major development platform. tags: - platform + - system tests: # Tests link to "windows" to ensure results come from Windows platform - "windows@VersionMark_CapturesVersions" @@ -21,6 +22,7 @@ sections: DEMA Consulting tools must support Linux for CI/CD and containerized environments. tags: - platform + - system tests: # Tests link to "ubuntu" to ensure results come from Linux platform - "ubuntu@VersionMark_CapturesVersions" @@ -33,6 +35,7 @@ sections: and macOS CI/CD runners. tags: - platform + - system tests: # Tests link to "macos" to ensure results come from macOS platform - "macos@VersionMark_CapturesVersions" @@ -44,6 +47,7 @@ sections: .NET 8 is an LTS release providing long-term stability for enterprise users. tags: - platform + - system tests: - "dotnet8.x@VersionMark_CapturesVersions" - "dotnet8.x@VersionMark_GeneratesMarkdownReport" @@ -54,6 +58,7 @@ sections: .NET 9 support enables users to leverage the latest .NET features. tags: - platform + - system tests: - "dotnet9.x@VersionMark_CapturesVersions" - "dotnet9.x@VersionMark_GeneratesMarkdownReport" @@ -64,6 +69,7 @@ sections: .NET 10 support ensures the tool remains compatible with the latest .NET ecosystem. tags: - platform + - system tests: - "dotnet10.x@VersionMark_CapturesVersions" - "dotnet10.x@VersionMark_GeneratesMarkdownReport" diff --git a/docs/reqstream/version-mark/publishing.yaml b/docs/reqstream/version-mark/publishing.yaml index 59302b3..169c349 100644 --- a/docs/reqstream/version-mark/publishing.yaml +++ b/docs/reqstream/version-mark/publishing.yaml @@ -23,6 +23,8 @@ sections: enabling integration with documentation systems and custom workflows. tags: - publish + children: + - VersionMark-Formatter-Structure tests: - Publishing_Format_MultipleCaptureFiles_ProducesConsolidatedReport - Publishing_Run_WithGlobPattern_ReadsMatchingFiles @@ -35,6 +37,8 @@ sections: within existing document structures and hierarchy requirements. tags: - publish + children: + - VersionMark-Formatter-MarkdownConsolidation tests: - Publishing_Format_WithCustomDepth_UsesCorrectHeadingLevel - Publishing_Run_WithReportDepth_UsesCorrectDepth @@ -58,6 +62,8 @@ sections: the report using standard glob patterns like versionmark-*.json. tags: - publish + children: + - VersionMark-Utilities-GlobMatch tests: - Publishing_Run_WithGlobPattern_ReadsMatchingFiles @@ -71,6 +77,7 @@ sections: - publish children: - VersionMark-VersionInfo-Load + - VersionMark-Formatter-JobId tests: - Publishing_Format_MultipleCaptureFiles_ProducesConsolidatedReport - Publishing_Format_IdenticalVersionsAcrossJobs_ConsolidatesVersions @@ -110,5 +117,7 @@ sections: helping users identify and fix data quality issues. tags: - publish + children: + - VersionMark-VersionInfo-Error tests: - Publishing_Run_WithMalformedJsonFile_ReportsError diff --git a/docs/reqstream/version-mark/utilities.yaml b/docs/reqstream/version-mark/utilities.yaml index e6fa95b..84f1903 100644 --- a/docs/reqstream/version-mark/utilities.yaml +++ b/docs/reqstream/version-mark/utilities.yaml @@ -14,6 +14,7 @@ sections: - VersionMark-GlobMatcher-FindFiles - VersionMark-GlobMatcher-AbsolutePaths - VersionMark-GlobMatcher-DeduplicatedSortedOutput + - VersionMark-OTS-FileSystemGlobbing tests: - GlobMatcher_FindMatchingFiles_RelativePattern_ReturnsMatchingFiles - GlobMatcher_FindMatchingFiles_AbsolutePattern_ReturnsMatchingFiles diff --git a/requirements.yaml b/requirements.yaml index b771ef3..5020a75 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -4,6 +4,17 @@ # This file defines the requirements for the VersionMark tool. # Requirements are verified through tests and documented in # docs/requirements_doc/ and docs/requirements_report/. +# +# root-tags identifies the tags that mark "root" requirements - product-facing +# system requirements and quality/process requirements that exist for their own +# sake and don't need a further parent. Every other requirement must trace up +# (via children links) to at least one root-tagged requirement, or it is +# reported as orphaned - a requirement implemented, tested, and documented but +# never connected to anything a user or the repository's compliance process +# actually needs. Because root-tags is configured here, orphan checking runs +# automatically on every "reqstream" invocation (including --lint and +# --enforce) without needing a --root-tags command-line flag. +root-tags: [system, quality] includes: - docs/reqstream/version-mark.yaml @@ -25,6 +36,7 @@ includes: - docs/reqstream/version-mark/utilities.yaml - docs/reqstream/version-mark/utilities/glob-matcher.yaml - docs/reqstream/version-mark/utilities/path-helpers.yaml + - docs/reqstream/quality.yaml - docs/reqstream/ots/xunit.yaml - docs/reqstream/ots/reqstream.yaml - docs/reqstream/ots/buildmark.yaml