requirements.yaml

# 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@",
# "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
#   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: SarifMark Requirements
    sections:
      - title: Command-Line Interface
        requirements:
          - id: SarifMark-Cli-Interface
            title: The tool shall provide a command-line interface.
            justification: >-
              A command-line interface enables automation, scripting, and integration into CI/CD pipelines,
              making the tool suitable for DevOps workflows and batch processing scenarios.
            tests:
              - IntegrationTest_VersionFlag_OutputsVersion
              - IntegrationTest_HelpFlag_OutputsUsageInformation

          - id: SarifMark-Cli-Version
            title: The tool shall display version information when requested.
            justification: >-
              Version information allows users to identify the tool version for troubleshooting, compatibility
              verification, and ensuring consistent behavior across different environments.
            tests:
              - IntegrationTest_VersionFlag_OutputsVersion
              - Context_Create_VersionFlag_SetsVersionTrue

          - id: SarifMark-Cli-Help
            title: The tool shall display help information when requested.
            justification: >-
              Help information improves discoverability and usability by providing users with guidance on
              available options, parameters, and usage patterns without consulting external documentation.
            tests:
              - IntegrationTest_HelpFlag_OutputsUsageInformation
              - Context_Create_HelpFlag_SetsHelpTrue

          - id: SarifMark-Cli-Silent
            title: The tool shall support silent mode to suppress console output.
            justification: >-
              Silent mode enables cleaner integration into automated workflows and CI/CD pipelines where console
              noise needs to be minimized, while still allowing log files to capture detailed information.
            tests:
              - IntegrationTest_SilentFlag_SuppressesOutput

          - id: SarifMark-Cli-Log
            title: The tool shall support writing output to a log file.
            justification: >-
              Log file support enables persistent record-keeping, debugging, and audit trails, especially valuable
              in automated environments where console output may not be readily available.
            tests:
              - IntegrationTest_LogFile_WritesOutputToFile

          - id: SarifMark-Cli-Enforce
            title: The tool shall support enforcing quality gate checks.
            justification: >-
              Quality gate enforcement enables the tool to act as a quality gate in CI/CD pipelines, failing
              builds when issues are detected and ensuring code quality standards are maintained.
            tests:
              - SarifMark_Enforcement

          - id: SarifMark-Cli-InvalidArgs
            title: The tool shall reject unknown command-line arguments.
            justification: >-
              Rejecting unknown arguments prevents silent failures from typos or incorrect parameters, ensuring
              users receive immediate feedback about misconfigured commands.
            tests:
              - IntegrationTest_UnknownArgument_ShowsError

      - title: SARIF Integration
        requirements:
          - id: SarifMark-Sarif-Reading
            title: The tool shall read SARIF 2.1.0 format files.
            justification: >-
              Support for SARIF 2.1.0 is essential as it is the standard format for static analysis results,
              enabling interoperability with a wide range of analysis tools and platforms.
            tests:
              - SarifMark_SarifReading
              - IntegrationTest_ValidSarifFile_ProcessesSuccessfully

          - id: SarifMark-Sarif-Validation
            title: The tool shall validate SARIF file format.
            justification: >-
              Format validation ensures the tool processes only well-formed SARIF files, preventing runtime
              errors and providing clear feedback when inputs are malformed or corrupted.
            tests:
              - SarifResults_Read_InvalidJson_ThrowsInvalidOperationException
              - SarifResults_Read_MissingVersion_ThrowsInvalidOperationException
              - SarifResults_Read_MissingRuns_ThrowsInvalidOperationException
              - SarifResults_Read_EmptyRuns_ThrowsInvalidOperationException

          - id: SarifMark-Sarif-ToolInfo
            title: The tool shall extract tool information from SARIF files.
            justification: >-
              Extracting tool information enables reports to identify which analysis tool generated the results,
              providing context and traceability for findings in the generated documentation.
            tests:
              - SarifResults_Read_MissingTool_ThrowsInvalidOperationException
              - SarifResults_Read_MissingDriver_ThrowsInvalidOperationException
              - SarifResults_Read_MissingToolName_UsesUnknown
              - SarifResults_Read_MissingToolVersion_UsesUnknown

          - id: SarifMark-Sarif-Results
            title: The tool shall extract results from SARIF files.
            justification: >-
              Result extraction is the core functionality that enables conversion of analysis findings into
              readable markdown reports, making issues accessible to developers and stakeholders.
            tests:
              - SarifResults_Read_NoResults_ReturnsValidResults
              - SarifResults_Read_EmptyResults_ReturnsValidResults
              - SarifResults_Read_WithResults_ReturnsValidResults

          - id: SarifMark-Sarif-Locations
            title: The tool shall extract location information from SARIF results.
            justification: >-
              Location information allows users to quickly identify where issues exist in their codebase,
              improving the actionability of analysis results by pinpointing specific files and lines.
            tests:
              - SarifResults_Read_WithLocations_ReturnsResultsWithLocationData

          - id: SarifMark-Sarif-FilePaths
            title: The tool shall require valid file paths for SARIF input.
            justification: >-
              Path validation ensures clear error messages when files are missing or incorrectly specified,
              improving user experience and preventing confusing runtime failures.
            tests:
              - SarifResults_Read_NullPath_ThrowsArgumentException
              - SarifResults_Read_EmptyPath_ThrowsArgumentException
              - SarifResults_Read_WhitespacePath_ThrowsArgumentException
              - SarifResults_Read_NonExistentFile_ThrowsFileNotFoundException

          - id: SarifMark-Sarif-Required
            title: The tool shall require the --sarif parameter for analysis.
            justification: >-
              Requiring explicit SARIF file specification ensures intentional operation and prevents accidental
              execution without proper input, improving tool safety and predictability.
            tests:
              - IntegrationTest_MissingSarifParameter_ShowsError

          - id: SarifMark-Sarif-Processing
            title: The tool shall process valid SARIF files successfully.
            justification: >-
              Successful processing of valid SARIF files is the fundamental capability that enables the tool to
              fulfill its primary purpose of converting analysis results to markdown documentation.
            tests:
              - IntegrationTest_ValidSarifFile_ProcessesSuccessfully

      - title: Report Generation
        requirements:
          - id: SarifMark-Rpt-Markdown
            title: The tool shall generate markdown reports from SARIF files.
            justification: >-
              Markdown report generation transforms machine-readable SARIF into human-readable documentation,
              enabling better understanding and communication of analysis results across development teams.
            tests:
              - IntegrationTest_GenerateReport_CreatesReportFile
              - SarifMark_MarkdownReportGeneration

          - id: SarifMark-Rpt-Depth
            title: The tool shall support configurable markdown heading depth.
            justification: >-
              Configurable heading depth allows reports to integrate seamlessly into existing documentation
              hierarchies, preventing heading level conflicts when reports are embedded in larger documents.
            tests:
              - IntegrationTest_ReportDepth_IsConfigurable

          - id: SarifMark-Rpt-Counts
            title: The tool shall display result counts in reports.
            justification: >-
              Result counts provide a quick summary of analysis findings, helping users understand the scope of
              issues at a glance and track improvements over time.
            tests:
              - SarifResults_ToMarkdown_NoResults_ShowsFoundNoResults
              - SarifResults_ToMarkdown_OneResult_UsesSingularForm

          - id: SarifMark-Rpt-Locations
            title: The tool shall display location information for results.
            justification: >-
              Displaying location information enables developers to quickly navigate to the source of issues,
              making the reports actionable and reducing time spent searching for problematic code.
            tests:
              - SarifResults_ToMarkdown_ResultWithoutLocation_ShowsNoLocation
              - SarifResults_ToMarkdown_ResultWithUriNoLine_ShowsUriOnly

          - id: SarifMark-Rpt-Headings
            title: The tool shall support custom headings in reports.
            justification: >-
              Custom headings allow users to tailor reports to their documentation standards and naming
              conventions, improving consistency across project documentation.
            tests:
              - SarifResults_ToMarkdown_CustomHeading_UsesProvidedHeading
              - SarifResults_ToMarkdown_NullHeading_UsesDefaultHeading
              - SarifResults_ToMarkdown_NoHeadingParameter_UsesDefaultHeading
              - Context_Create_HeadingArgument_SetsHeading

          - id: SarifMark-Rpt-LineBreaks
            title: The tool shall format multiple results with proper line breaks.
            justification: >-
              Proper line breaks between results ensure readability and visual separation in generated markdown,
              making it easier to distinguish between different findings in the report.
            tests:
              - SarifResults_ToMarkdown_MultipleResults_EnforcesLineBreaks

      - title: Validation and Testing
        requirements:
          - id: SarifMark-Val-Mode
            title: The tool shall support self-validation mode.
            justification: >-
              Self-validation mode enables verification that the tool operates correctly in the user's
              environment, ensuring proper installation and configuration.
            tests:
              - IntegrationTest_ValidateFlag_RunsSelfValidation

          - id: SarifMark-Val-ResultFiles
            title: The tool shall write validation results to test result files.
            justification: >-
              Writing test results to files enables integration with CI/CD systems and provides persistent
              records of validation outcomes for tracking quality trends and compliance.
            tests:
              - IntegrationTest_ValidateFlag_RunsSelfValidation

          - id: SarifMark-Val-TrxFormat
            title: The tool shall support TRX format for test results.
            justification: >-
              TRX format support enables integration with Microsoft testing ecosystems and Azure DevOps,
              providing native compatibility with Visual Studio and .NET tooling.
            tests:
              - IntegrationTest_ValidateFlag_RunsSelfValidation

          - id: SarifMark-Val-JUnitFormat
            title: The tool shall support JUnit format for test results.
            justification: >-
              JUnit format support enables broad compatibility with CI/CD platforms like Jenkins, GitHub Actions,
              and GitLab CI, which commonly use this standard format for test reporting.
            tests:
              - IntegrationTest_ValidateFlag_RunsSelfValidation

      - title: Quality Enforcement
        requirements:
          - id: SarifMark-Enf-Mode
            title: The tool shall support enforcement mode to fail on issues found.
            justification: >-
              Enforcement mode enables the tool to act as a quality gate in CI/CD pipelines, preventing code
              with analysis issues from being merged or deployed, thereby maintaining code quality standards.
            tests:
              - IntegrationTest_EnforceFlagWithIssues_ReturnsError
              - SarifMark_Enforcement

          - id: SarifMark-Enf-ExitCode
            title: The tool shall return non-zero exit code when issues found in enforcement mode.
            justification: >-
              Non-zero exit codes signal failure to CI/CD systems and scripts, enabling automated build failures
              and preventing the progression of problematic code through deployment pipelines.
            tests:
              - IntegrationTest_EnforceFlagWithIssues_ReturnsError
              - SarifMark_Enforcement

      - title: Platform Support
        requirements:
          - id: SarifMark-Plt-Windows
            title: The tool shall run on Windows operating systems.
            justification: >-
              Windows support ensures the tool is accessible to developers using Microsoft platforms, which are
              prevalent in enterprise environments and .NET development ecosystems.
            tests:
              - windows@IntegrationTest_VersionFlag_OutputsVersion
              - windows@IntegrationTest_HelpFlag_OutputsUsageInformation
              - windows@IntegrationTest_ValidateFlag_RunsSelfValidation

          - id: SarifMark-Plt-Linux
            title: The tool shall run on Linux operating systems.
            justification: >-
              Linux support is essential for cloud-native development and CI/CD pipelines, as most modern build
              systems and container environments run on Linux.
            tests:
              - ubuntu@IntegrationTest_VersionFlag_OutputsVersion
              - ubuntu@IntegrationTest_HelpFlag_OutputsUsageInformation
              - ubuntu@IntegrationTest_ValidateFlag_RunsSelfValidation

          - id: SarifMark-Plt-Net8
            title: The tool shall support .NET 8.0 runtime.
            justification: >-
              .NET 8.0 support ensures compatibility with the current Long-Term Support release, providing
              stability and widespread adoption for enterprise users.
            tests:
              - dotnet8.x@SarifMark_SarifReading
              - dotnet8.x@SarifMark_MarkdownReportGeneration
              - dotnet8.x@SarifMark_Enforcement

          - id: SarifMark-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,
              ensuring the tool remains current with the .NET ecosystem.
            tests:
              - dotnet9.x@SarifMark_SarifReading
              - dotnet9.x@SarifMark_MarkdownReportGeneration
              - dotnet9.x@SarifMark_Enforcement

          - id: SarifMark-Plt-Net10
            title: The tool shall support .NET 10.0 runtime.
            justification: >-
              .NET 10.0 support provides forward compatibility and ensures the tool remains viable as users adopt
              future .NET versions, extending the tool's lifespan and relevance.
            tests:
              - dotnet10.x@SarifMark_SarifReading
              - dotnet10.x@SarifMark_MarkdownReportGeneration
              - dotnet10.x@SarifMark_Enforcement

      - title: OTS Software
        requirements:
          - id: SarifMark-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:
              - SarifResults_Read_NoResults_ReturnsValidResults
              - SarifResults_Read_WithResults_ReturnsValidResults
              - SarifResults_ToMarkdown_NoResults_ShowsFoundNoResults
              - Context_Create_VersionFlag_SetsVersionTrue
              - Context_Create_HelpFlag_SetsHelpTrue

          - id: SarifMark-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: SarifMark-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: SarifMark-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: SarifMark-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