Rename --report-depth to --depth, keep legacy alias

[Copilot]

Pull Request

Description

Renames --report-depth to --depth as the canonical CLI argument. --report-depth remains functional as an undocumented legacy alias. --depth now also controls the depth of self-validation markdown output (previously it had no effect there).

Source changes

• Context.cs — --depth is the primary case; --report-depth falls through to the same handler; ReportDepth property renamed to Depth on both the outer Context class and the inner ArgumentParser class; XML doc updated to "Gets the markdown depth."
• Program.cs — help text updated to --depth <depth>; uses context.Depth
• Validation.cs — self-test runner now forwards --depth <context.Depth> so depth applies to self-validation output

Tests

• Added Cli_DepthParameter_SetsDepth (subsystem) and four Context_Create_Depth_* (unit) tests for --depth
• Legacy --report-depth tests retained to verify backward compatibility
• IntegrationTests.cs primary test uses --depth; added legacy acceptance test
• ProgramTests.cs help assertion updated to check --depth
• Added SelfTest_DepthParameter_AffectsSelfValidationReport — explicitly verifies that passing --depth 2 causes the self-validation markdown report generation test to pass with depth-2 headings (##), confirming --depth actually affects the self-validation markdown output
• All test assertions updated to reference context.Depth

Docs & requirements

• README.md, docs/user_guide/introduction.md, design docs updated to --depth
• Design doc tables in context.md and cli.md updated: property column renamed from ReportDepth to Depth
• Requirements YAMLs updated with new primary test references and legacy test coverage; SelfTest_DepthParameter_AffectsSelfValidationReport linked to SarifMark-Cli-ReportDepth; context.yaml description updated from set ReportDepth to set Depth; test name references updated to Cli_DepthParameter_SetsDepth and Context_Create_DepthParameter_SetsDepth
• CI workflow updated to --depth 1

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code quality improvement

Related Issues

Pre-Submission Checklist

Before submitting this pull request, ensure you have completed the following:

Build and Test

• Code builds successfully: dotnet build --configuration Release
• All unit tests pass: dotnet test --configuration Release
• Self-validation tests pass:
  dotnet run --project src/DemaConsulting.SarifMark --configuration Release --framework net10.0
--no-build -- --validate
• Code produces zero warnings

Code Quality

• Code formatting is correct: dotnet format --verify-no-changes
• New code has appropriate XML documentation comments
• Static analyzer warnings have been addressed

Quality Checks

Please run the following checks before submitting:

• All linters pass: ./lint.sh (Unix/macOS) or cmd /c lint.bat / ./lint.bat (Windows)

Testing

• Added unit tests for new functionality
• Updated existing tests if behavior changed
• All tests follow the AAA (Arrange, Act, Assert) pattern
• Test coverage is maintained or improved

Documentation

• Updated README.md (if applicable)
• Updated ARCHITECTURE.md (if applicable)
• Added code examples for new features (if applicable)
• Updated requirements.yaml (if applicable)

Additional Notes

--report-depth is intentionally kept working but removed from all documentation. No behavior change for existing users. The internal ReportDepth property has been renamed to Depth to align with the canonical CLI argument name. Test methods that exercise the --depth flag are named consistently with the property (SetsDepth), while legacy tests covering --report-depth retain their existing names.

[Malcolmnixon]

@copilot Do you actually test that --depth affects the self-validation markdown report depth?

[Copilot]

@copilot Do you actually test that --depth affects the self-validation markdown report depth?

Previously, --depth was exercised inside Validation.cs's RunMarkdownReportGenerationTest (it builds the heading prefix from context.ReportDepth and verifies it), but there was no explicit subsystem test that passed a non-default depth and confirmed the effect.

Added SelfTest_DepthParameter_AffectsSelfValidationReport in commit 0f719fd: it creates a context with --validate --depth 2, runs Validation.Run, and asserts that SarifMark_MarkdownReportGeneration - Passed appears in the output — which only happens when the internal test confirms a ##-level heading in the generated report.

[Copilot]

Pull request overview

This PR renames the CLI option for controlling markdown heading depth from --report-depth to --depth (keeping --report-depth as a legacy alias), and ensures that the selected depth is also applied during self-validation markdown report generation.

Changes:

• Update CLI parsing and internal API to use Context.Depth as the canonical heading depth (with --report-depth retained as an alias).
• Apply the configured depth to both normal markdown report generation and self-validation markdown report generation.
• Update tests, requirements, docs, and CI workflow usage to prefer --depth.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
test/DemaConsulting.SarifMark.Tests/SelfTest/SelfTestTests.cs	Adds a self-test asserting --depth affects self-validation report generation outcomes.
test/DemaConsulting.SarifMark.Tests/ProgramTests.cs	Updates help output assertion to expect --depth.
test/DemaConsulting.SarifMark.Tests/IntegrationTests.cs	Switches integration coverage to --depth and adds legacy alias acceptance coverage.
test/DemaConsulting.SarifMark.Tests/Cli/ContextTests.cs	Adds unit tests for --depth parsing/validation and updates legacy tests to assert Depth.
test/DemaConsulting.SarifMark.Tests/Cli/CliTests.cs	Adds subsystem test for --depth and updates legacy assertions to use Depth.
src/DemaConsulting.SarifMark/SelfTest/Validation.cs	Forwards --depth into the markdown report generation self-validation test and validates heading prefix accordingly.
src/DemaConsulting.SarifMark/Program.cs	Updates help text and report generation to use context.Depth.
src/DemaConsulting.SarifMark/Cli/Context.cs	Renames ReportDepth to Depth and parses --depth with a --report-depth alias.
docs/user_guide/introduction.md	Updates user documentation to --depth.
docs/reqstream/sarifmark/cli/context.yaml	Updates requirement text and adds --depth test references while retaining legacy coverage.
docs/reqstream/sarifmark/cli/cli.yaml	Updates CLI requirement to --depth and links new self-test.
docs/design/sarifmark/program.md	Updates design doc help flag listing to --depth.
docs/design/sarifmark/cli/context.md	Updates flag naming and legacy alias narrative (but see review comment re: property name).
docs/design/sarifmark/cli/cli.md	Updates flag naming (but see review comment re: property name).
README.md	Updates CLI options list to --depth.
.github/workflows/build.yaml	Updates workflow invocation to use --depth 1.

Comments suppressed due to low confidence (2)

test/DemaConsulting.SarifMark.Tests/IntegrationTests.cs:335

• The summary comment was updated to say "depth parameter", but the test method name is still IntegrationTest_ReportDepth_IsConfigurable. Consider renaming the test to IntegrationTest_Depth_IsConfigurable (and updating any requirement links) to reflect the canonical flag name.

    /// <summary>
    ///     Test that depth parameter is configurable.
    /// </summary>
    [TestMethod]
    public void IntegrationTest_ReportDepth_IsConfigurable()
    {

src/DemaConsulting.SarifMark/Program.cs:203

• SarifResults.ToMarkdown throws ArgumentOutOfRangeException when depth is outside 1–6, but this report generation block doesn’t catch it (current catch filter excludes it). Since Context.Depth only validates >= 1, passing --depth 7 will crash the program instead of producing a user-friendly error. Consider validating Depth to be within 1–6 during argument parsing and/or catching ArgumentOutOfRangeException here and emitting a clear message (e.g., "--depth must be between 1 and 6").

            context.WriteLine($"Writing report to {context.ReportFile}...");
            try
            {
                var markdown = sarifResults.ToMarkdown(context.Depth, context.Heading);
                File.WriteAllText(context.ReportFile, markdown);
                context.WriteLine("Report generated successfully.");
            }
            catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or ArgumentException or NotSupportedException)
            {
                context.WriteError($"Error: Failed to write report: {ex.Message}");
            }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Malcolmnixon]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

Done in commit 73f5aff:

• Cli_DepthParameter_SetsReportDepth → Cli_DepthParameter_SetsDepth
• Context_Create_DepthParameter_SetsReportDepth → Context_Create_DepthParameter_SetsDepth
• XML doc on Depth property updated to "Gets the markdown depth." (both outer class and inner ArgumentParser)
• Design doc tables in context.md and cli.md updated from ReportDepth to Depth
• Requirements YAML test references updated to match the renamed methods