diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 6e61d2c..5548a44 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -7,6 +7,7 @@ # Processed in order; prefix a pattern with '!' to exclude. needs-review: - "**/*.cs" # All C# source and test files + - "requirements.yaml" # Root requirements file - "docs/reqstream/**/*.yaml" # Requirements files - "docs/design/**/*.md" # Design documents - "!**/obj/**" # Exclude build output @@ -24,49 +25,86 @@ evidence-source: # 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: TemplateTool-Context - title: Review of Template DotNet Tool Context Unit - paths: - - "docs/reqstream/cli/unit-context.yaml" - - "src/**/Context.cs" - - "test/**/ContextTests.cs" - + # Software unit reviews - one per unit - id: TemplateTool-Program title: Review of Template DotNet Tool Program Unit paths: - - "docs/reqstream/unit-program.yaml" - - "src/**/Program.cs" - - "test/**/ProgramTests.cs" - - "test/**/IntegrationTests.cs" - - "test/**/Runner.cs" - - "test/**/AssemblyInfo.cs" + - "docs/reqstream/unit-program.yaml" # requirements + - "docs/design/program.md" # design + - "src/**/Program.cs" # implementation + - "test/**/ProgramTests.cs" # unit tests + + - id: TemplateTool-Context + title: Review of Template DotNet Tool Context Unit + paths: + - "docs/reqstream/cli/unit-context.yaml" # requirements + - "docs/design/cli/context.md" # design + - "src/**/Cli/Context.cs" # implementation + - "test/**/Cli/ContextTests.cs" # unit tests - id: TemplateTool-Validation title: Review of Template DotNet Tool Validation Unit paths: - - "docs/reqstream/self-test/unit-validation.yaml" - - "src/**/Validation.cs" - - "test/**/ValidationTests.cs" + - "docs/reqstream/self-test/unit-validation.yaml" # requirements + - "docs/design/self-test/validation.md" # design + - "src/**/SelfTest/Validation.cs" # implementation + - "test/**/SelfTest/ValidationTests.cs" # unit tests - id: TemplateTool-PathHelpers title: Review of Template DotNet Tool PathHelpers Unit paths: - - "docs/reqstream/utilities/unit-path-helpers.yaml" - - "src/**/PathHelpers.cs" - - "test/**/PathHelpersTests.cs" + - "docs/reqstream/utilities/unit-path-helpers.yaml" # requirements + - "docs/design/utilities/path-helpers.md" # design + - "src/**/Utilities/PathHelpers.cs" # implementation + - "test/**/Utilities/PathHelpersTests.cs" # unit tests + + # Subsystem reviews + - id: TemplateTool-Cli + title: Review of Template DotNet Tool Cli subsystem (command-line interface) + paths: + - "docs/reqstream/cli/subsystem-cli.yaml" # subsystem requirements + - "docs/design/cli/cli.md" # subsystem design + - "docs/design/cli/context.md" # Context unit design + - "docs/design/program.md" # Program unit design + + - id: TemplateTool-SelfTest + title: Review of Template DotNet Tool SelfTest subsystem (self-validation) + paths: + - "docs/reqstream/self-test/subsystem-self-test.yaml" # subsystem requirements + - "docs/design/self-test/self-test.md" # subsystem design + - "docs/design/self-test/validation.md" # Validation unit design + + - id: TemplateTool-Utilities + title: Review of Template DotNet Tool Utilities subsystem (shared utilities) + paths: + - "docs/reqstream/utilities/subsystem-utilities.yaml" # subsystem requirements + - "docs/design/utilities/utilities.md" # subsystem design + - "docs/design/utilities/path-helpers.md" # PathHelpers unit design + + # System review - covers system-level behavior validated through integration tests + - id: TemplateTool-System + title: Review of Template DotNet Tool system-level behavior and integration + paths: + - "docs/reqstream/templatetool-system.yaml" # system requirements + - "docs/reqstream/platform-requirements.yaml" # platform requirements + - "docs/design/introduction.md" # design introduction and architecture + - "test/**/IntegrationTests.cs" # integration tests + - "test/**/Runner.cs" # test infrastructure + - "test/**/AssemblyInfo.cs" # test infrastructure - id: TemplateTool-Design title: Review of Template DotNet Tool Software Design Document paths: - - "docs/design/**/*.md" + - "docs/design/**/*.md" # all design documents - # Platform and OTS dependency reviews - - id: Platform-Support - title: Review of Platform and Runtime Support Requirements + # All-requirements review + - id: TemplateTool-AllRequirements + title: Review of all Template DotNet Tool requirements files paths: - - "docs/reqstream/platform-requirements.yaml" + - "requirements.yaml" # root requirements file + - "docs/reqstream/**/*.yaml" # all requirements files + # OTS dependency reviews - id: OTS-Dependencies title: Review of Off-The-Shelf Software Dependencies paths: diff --git a/AGENTS.md b/AGENTS.md index 2f4435c..3cab468 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -92,6 +92,8 @@ compliance gates on every CI/CD run instead of as a last-mile activity. ## Project Structure Template - `docs/` - Documentation and compliance artifacts + - `design/` - Detailed design documents + - `introduction.md` - System/Subsystem/Unit breakdown for this repository - `reqstream/` - Subsystem requirements YAML files (included by root requirements.yaml) - Auto-generated reports (requirements, justifications, trace matrix) - `src/` - Source code files diff --git a/docs/design/cli/cli.md b/docs/design/cli/cli.md new file mode 100644 index 0000000..301ac66 --- /dev/null +++ b/docs/design/cli/cli.md @@ -0,0 +1,47 @@ +# Cli Subsystem + + + +The `Cli` subsystem provides the command-line interface for the Template DotNet Tool. +It is responsible for accepting user input from the command line and routing output to +the console and an optional log file. + +## Overview + + + +The `Cli` subsystem acts as the primary boundary between the user's shell invocation and +the tool's internal logic. It owns argument parsing, output formatting, and error tracking. +All other subsystems receive a `Context` object from the `Cli` subsystem to read parsed +flags and write output. + +## Units + + + +The `Cli` subsystem contains the following software unit: + +| Unit | File | Responsibility | +|-----------|------------------|---------------------------------------------------| +| `Context` | `Cli/Context.cs` | Argument parsing, output channels, and exit code. | + +## Interfaces + + + +The `Cli` subsystem exposes the following interface to the rest of the tool: + +| Interface | Direction | Description | +|----------------------|-----------|---------------------------------------------------------------| +| `Context.Create` | Outbound | Factory method constructing a `Context` from `string[] args`. | +| `Context.WriteLine` | Outbound | Writes a message to console and optional log file. | +| `Context.WriteError` | Outbound | Writes an error to stderr and sets the error exit code. | +| `Context.ExitCode` | Outbound | Returns 0 for success or 1 when errors have been reported. | + +## Interactions + + + +The `Cli` subsystem has no dependencies on other tool subsystems. It uses only .NET base +class library types. The `Program` unit at system level creates the `Context` and passes it +to all subsystems that need to produce output. diff --git a/docs/design/context.md b/docs/design/cli/context.md similarity index 100% rename from docs/design/context.md rename to docs/design/cli/context.md diff --git a/docs/design/definition.yaml b/docs/design/definition.yaml index 1c193ac..f1f3981 100644 --- a/docs/design/definition.yaml +++ b/docs/design/definition.yaml @@ -1,14 +1,21 @@ --- resource-path: - docs/design + - docs/design/cli + - docs/design/self-test + - docs/design/utilities - docs/template + input-files: - docs/design/title.txt - docs/design/introduction.md - docs/design/program.md - - docs/design/context.md - - docs/design/validation.md - - docs/design/path-helpers.md + - docs/design/cli/cli.md + - docs/design/cli/context.md + - docs/design/self-test/self-test.md + - docs/design/self-test/validation.md + - docs/design/utilities/utilities.md + - docs/design/utilities/path-helpers.md template: template.html table-of-contents: true number-sections: true diff --git a/docs/design/self-test/self-test.md b/docs/design/self-test/self-test.md new file mode 100644 index 0000000..79763b6 --- /dev/null +++ b/docs/design/self-test/self-test.md @@ -0,0 +1,45 @@ +# SelfTest Subsystem + + + +The `SelfTest` subsystem provides the self-validation framework for the Template DotNet Tool. +It runs a built-in suite of tests to demonstrate the tool is functioning correctly in the +deployment environment. + +## Overview + + + +The `SelfTest` subsystem is invoked when the user passes `--validate` on the command line. +It exercises the tool's own capabilities and reports a pass/fail summary. It can also write +test results to a file in TRX or JUnit XML format for integration with CI/CD pipelines. + +## Units + + + +The `SelfTest` subsystem contains the following software unit: + +| Unit | File | Responsibility | +|--------------|--------------------------|----------------------------------------------------| +| `Validation` | `SelfTest/Validation.cs` | Orchestrating and executing self-validation tests. | + +## Interfaces + + + +The `SelfTest` subsystem exposes the following interface to the rest of the tool: + +| Interface | Direction | Description | +|------------------|-----------|-----------------------------------------------------------------------| +| `Validation.Run` | Outbound | Runs all self-validation tests, prints a summary, and writes results. | + +## Interactions + + + +| Dependency | Direction | Purpose | +|---------------|-----------|--------------------------------------------------------------| +| `Context` | Uses | Output channel for header lines, test summaries, and errors. | +| `Program` | Uses | `Program.Run` is called internally to exercise the tool. | +| `PathHelpers` | Uses | `SafePathCombine` for constructing log file paths in tests. | diff --git a/docs/design/validation.md b/docs/design/self-test/validation.md similarity index 100% rename from docs/design/validation.md rename to docs/design/self-test/validation.md diff --git a/docs/design/path-helpers.md b/docs/design/utilities/path-helpers.md similarity index 100% rename from docs/design/path-helpers.md rename to docs/design/utilities/path-helpers.md diff --git a/docs/design/utilities/utilities.md b/docs/design/utilities/utilities.md new file mode 100644 index 0000000..f6e756c --- /dev/null +++ b/docs/design/utilities/utilities.md @@ -0,0 +1,42 @@ +# Utilities Subsystem + + + +The `Utilities` subsystem provides shared utility functions for the Template DotNet Tool. +It supplies reusable, independently testable helpers that are consumed by other subsystems. + +## Overview + + + +The `Utilities` subsystem contains general-purpose helpers that do not belong to any +specific feature subsystem. Its primary responsibility is safe file-path manipulation, +protecting callers from path-traversal vulnerabilities when constructing paths from +external inputs. + +## Units + + + +The `Utilities` subsystem contains the following software unit: + +| Unit | File | Responsibility | +|---------------|----------------------------|---------------------------------------------| +| `PathHelpers` | `Utilities/PathHelpers.cs` | Safe path combination and traversal checks. | + +## Interfaces + + + +The `Utilities` subsystem exposes the following interface to the rest of the tool: + +| Interface | Direction | Description | +|-------------------------------|-----------|------------------------------------------------------------| +| `PathHelpers.SafePathCombine` | Outbound | Combines two path segments, rejecting traversal sequences. | + +## Interactions + + + +`PathHelpers` has no dependencies on other tool units or subsystems. It uses only .NET base +class library types (`Path`, `ArgumentNullException`). diff --git a/docs/reqstream/cli/subsystem-cli.yaml b/docs/reqstream/cli/subsystem-cli.yaml new file mode 100644 index 0000000..77953ac --- /dev/null +++ b/docs/reqstream/cli/subsystem-cli.yaml @@ -0,0 +1,118 @@ +--- +# Cli Subsystem Requirements +# +# PURPOSE: +# - Define requirements for the TemplateDotNetTool Cli subsystem +# - The Cli subsystem spans Context.cs (command-line argument parsing and I/O) +# - Subsystem requirements describe the externally visible command-line interface behavior + +sections: + - title: Cli Subsystem Requirements + requirements: + - id: Template-Cli-Context + title: The Cli subsystem shall implement a Context class for command-line argument handling. + justification: | + Provides a standardized approach to command-line argument parsing and output + handling across all DEMA Consulting DotNet Tools. The Context class encapsulates + all parsed flags and output channels so that the rest of the tool has a single, + consistent entry point for CLI interaction. + tests: + - Context_Create_NoArguments_ReturnsDefaultContext + - Context_Create_VersionFlag_SetsVersionTrue + - Context_Create_SilentFlag_SetsSilentTrue + - Context_Create_LogFlag_OpensLogFile + - Context_Create_UnknownArgument_ThrowsArgumentException + + - id: Template-Cli-Version + title: The Cli subsystem shall support -v and --version flags to signal version display. + justification: | + Users need to quickly identify the version of the tool they are using for + troubleshooting and compatibility verification. + tests: + - Context_Create_VersionFlag_SetsVersionTrue + - Context_Create_ShortVersionFlag_SetsVersionTrue + - Program_Run_WithVersionFlag_DisplaysVersionOnly + - Program_Version_ReturnsNonEmptyString + - IntegrationTest_VersionFlag_OutputsVersion + + - id: Template-Cli-Help + title: The Cli subsystem shall support -?, -h, and --help flags to signal help display. + justification: | + Users need access to command-line usage documentation without requiring + external resources. + tests: + - Context_Create_HelpFlag_SetsHelpTrue + - Context_Create_ShortHelpFlag_H_SetsHelpTrue + - Context_Create_ShortHelpFlag_Question_SetsHelpTrue + - Program_Run_WithHelpFlag_DisplaysUsageInformation + - IntegrationTest_HelpFlag_OutputsUsageInformation + + - id: Template-Cli-Silent + title: The Cli subsystem shall support --silent flag to suppress console output. + justification: | + Enables automated scripts and CI/CD pipelines to run the tool without + cluttering output logs. + tests: + - Context_Create_SilentFlag_SetsSilentTrue + - Context_WriteLine_Silent_DoesNotWriteToConsole + - IntegrationTest_SilentFlag_SuppressesOutput + + - id: Template-Cli-Validate + title: The Cli subsystem shall support --validate flag to signal self-validation. + justification: | + Provides a built-in mechanism to verify the tool is functioning correctly + in the deployment environment. + tests: + - Context_Create_ValidateFlag_SetsValidateTrue + - Program_Run_WithValidateFlag_RunsValidation + - IntegrationTest_ValidateFlag_RunsValidation + + - id: Template-Cli-Results + title: The Cli subsystem shall support --results flag to specify a test results output file. + justification: | + Enables integration with CI/CD systems that expect standard test result formats. + tests: + - Context_Create_ResultsFlag_SetsResultsFile + - Context_Create_ResultsFlag_WithoutValue_ThrowsArgumentException + - IntegrationTest_ValidateWithResults_GeneratesTrxFile + - IntegrationTest_ValidateWithResults_GeneratesJUnitFile + + - id: Template-Cli-Log + title: The Cli subsystem shall support --log flag to write output to a log file. + justification: | + Provides persistent logging for debugging and audit trails. + tests: + - Context_Create_LogFlag_OpensLogFile + - Context_Create_LogFlag_WithoutValue_ThrowsArgumentException + - Context_WriteError_WritesToLogFile + - IntegrationTest_LogFlag_WritesOutputToFile + + - id: Template-Cli-ErrorOutput + title: The Cli subsystem shall write error messages to stderr. + justification: | + Error messages must be written to stderr so they remain visible to the user + without polluting stdout, which consumers may pipe or redirect for data capture. + tests: + - Context_WriteError_NotSilent_WritesToConsole + - Context_WriteError_SetsErrorExitCode + - IntegrationTest_UnknownArgument_ReturnsError + + - id: Template-Cli-InvalidArgs + title: The Cli subsystem shall reject unknown or malformed command-line arguments with a descriptive error. + justification: | + Providing clear feedback for invalid arguments helps users quickly correct + mistakes and prevents silent misconfiguration. + tests: + - Context_Create_UnknownArgument_ThrowsArgumentException + - Context_Create_LogFlag_WithoutValue_ThrowsArgumentException + - Context_Create_ResultsFlag_WithoutValue_ThrowsArgumentException + - IntegrationTest_UnknownArgument_ReturnsError + + - id: Template-Cli-ExitCode + title: The Cli subsystem shall return a non-zero exit code on failure. + justification: | + Callers (scripts, CI/CD pipelines) must be able to detect failure conditions + programmatically via the process exit code. + tests: + - Context_WriteError_SetsErrorExitCode + - IntegrationTest_UnknownArgument_ReturnsError diff --git a/docs/reqstream/self-test/subsystem-self-test.yaml b/docs/reqstream/self-test/subsystem-self-test.yaml new file mode 100644 index 0000000..5249289 --- /dev/null +++ b/docs/reqstream/self-test/subsystem-self-test.yaml @@ -0,0 +1,40 @@ +--- +# SelfTest Subsystem Requirements +# +# PURPOSE: +# - Define requirements for the TemplateDotNetTool SelfTest subsystem +# - The SelfTest subsystem spans Validation.cs (self-validation test execution) +# - Subsystem requirements describe the self-validation mechanism for tool qualification +# in regulated environments + +sections: + - title: SelfTest Subsystem Requirements + requirements: + - id: Template-SelfTest-Qualification + title: The tool shall provide a self-validation mechanism to qualify the tool in its deployment environment. + justification: | + In regulated environments, tool qualification evidence is required to demonstrate + that the tool functions correctly in its deployment environment before it is used + to generate compliance artifacts. The SelfTest subsystem provides a built-in + self-validation suite that exercises core behaviors and produces a pass/fail + summary, enabling quality assurance teams to obtain tool qualification evidence + without requiring a separate test harness. + tests: + - Validation_Run_NullContext_ThrowsArgumentNullException + - Validation_Run_WithSilentContext_PrintsSummary + - Validation_Run_WithSilentContext_ExitCodeIsZero + - IntegrationTest_ValidateFlag_RunsValidation + + - id: Template-SelfTest-ResultsOutput + title: The tool shall write self-validation results to a standard test result file when --results is provided. + justification: | + CI/CD pipelines and requirements traceability tools (such as ReqStream) consume + test result files in standard formats. By supporting both TRX (MSTest) and JUnit + XML output, the SelfTest subsystem enables self-validation results to be fed + directly into pipeline tooling and traceability reports without additional + conversion steps, satisfying audit trail requirements. + tests: + - Validation_Run_WithTrxResultsFile_WritesTrxFile + - Validation_Run_WithXmlResultsFile_WritesXmlFile + - IntegrationTest_ValidateWithResults_GeneratesTrxFile + - IntegrationTest_ValidateWithResults_GeneratesJUnitFile diff --git a/docs/reqstream/templatetool-system.yaml b/docs/reqstream/templatetool-system.yaml new file mode 100644 index 0000000..8edc86c --- /dev/null +++ b/docs/reqstream/templatetool-system.yaml @@ -0,0 +1,68 @@ +--- +# TemplateDotNetTool System-Level Requirements +# +# PURPOSE: +# - Define system-level requirements describing what end-users need the tool to provide +# - These requirements capture the externally visible behavior of the complete system +# - System requirements are validated through integration tests that exercise the +# published dotnet DLL end-to-end + +sections: + - title: System-Level Requirements + requirements: + - id: Template-System-Version + title: The tool shall display version information when the version flag is provided. + justification: | + Users need to quickly identify the version of the tool they are using for + troubleshooting and compatibility verification. The version display must + work from a standard dotnet invocation without additional configuration. + tests: + - IntegrationTest_VersionFlag_OutputsVersion + + - id: Template-System-Help + title: The tool shall display usage information when the help flag is provided. + justification: | + Users need access to command-line usage documentation without requiring + external resources. Help output must be accessible from a standard dotnet + invocation and must list the available options so that users can self-serve. + tests: + - IntegrationTest_HelpFlag_OutputsUsageInformation + + - id: Template-System-Validate + title: The tool shall execute self-validation tests when the validate flag is provided. + justification: | + Regulated environments require tool qualification evidence to demonstrate + that the tool functions correctly in its deployment environment before it + is used to generate compliance artifacts. The validation mode exercises + core behaviors and produces a structured test result file, providing the + qualification evidence required by quality management systems. + tests: + - IntegrationTest_ValidateFlag_RunsValidation + - IntegrationTest_ValidateWithResults_GeneratesTrxFile + - IntegrationTest_ValidateWithResults_GeneratesJUnitFile + + - id: Template-System-Silent + title: The tool shall suppress console output when the silent flag is provided. + justification: | + Enables automated scripts and CI/CD pipelines to run the tool without + cluttering output logs when only the exit code is needed. + tests: + - IntegrationTest_SilentFlag_SuppressesOutput + + - id: Template-System-Log + title: The tool shall write output to a log file when the log flag is provided. + justification: | + Provides persistent logging for debugging and compliance audit trails. + Log files enable post-run inspection of tool output without requiring + console capture. + tests: + - IntegrationTest_LogFlag_WritesOutputToFile + + - id: Template-System-ErrorHandling + title: The tool shall return a non-zero exit code and report an error for unrecognized arguments. + justification: | + Clear feedback for unrecognized arguments helps users quickly correct + mistakes. A non-zero exit code enables CI/CD pipelines to detect and + surface misconfiguration failures automatically. + tests: + - IntegrationTest_UnknownArgument_ReturnsError diff --git a/docs/reqstream/utilities/subsystem-utilities.yaml b/docs/reqstream/utilities/subsystem-utilities.yaml new file mode 100644 index 0000000..3904ba3 --- /dev/null +++ b/docs/reqstream/utilities/subsystem-utilities.yaml @@ -0,0 +1,24 @@ +--- +# Utilities Subsystem Requirements +# +# PURPOSE: +# - Define requirements for the TemplateDotNetTool Utilities subsystem +# - The Utilities subsystem spans PathHelpers.cs (safe path-combination utilities) +# - Subsystem requirements describe the shared utility behavior available to all other subsystems + +sections: + - title: Utilities Subsystem Requirements + requirements: + - id: Template-Utilities-SafePaths + title: The Utilities subsystem shall provide safe file path manipulation that prevents path traversal. + justification: | + The Utilities subsystem provides shared path utilities consumed by other subsystems. + When constructing file paths from caller-supplied inputs, the subsystem must reject + path traversal sequences (such as '..') and absolute paths to prevent unintended + file system access. This requirement captures the subsystem-level safety guarantee + that all consumers of the Utilities subsystem can rely upon. + tests: + - PathHelpers_SafePathCombine_ValidPaths_CombinesCorrectly + - PathHelpers_SafePathCombine_PathTraversalWithDoubleDots_ThrowsArgumentException + - PathHelpers_SafePathCombine_AbsolutePath_ThrowsArgumentException + - PathHelpers_SafePathCombine_NestedPaths_CombinesCorrectly diff --git a/requirements.yaml b/requirements.yaml index 2f2d9c3..667ad8f 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -1,9 +1,13 @@ --- # Root requirements file - includes all system, unit, platform, and OTS requirements includes: + - docs/reqstream/templatetool-system.yaml - docs/reqstream/unit-program.yaml + - docs/reqstream/cli/subsystem-cli.yaml - docs/reqstream/cli/unit-context.yaml + - docs/reqstream/self-test/subsystem-self-test.yaml - docs/reqstream/self-test/unit-validation.yaml + - docs/reqstream/utilities/subsystem-utilities.yaml - docs/reqstream/utilities/unit-path-helpers.yaml - docs/reqstream/platform-requirements.yaml - docs/reqstream/ots-mstest.yaml