feat: add --depth command-line argument to VersionMark

[Copilot]

Pull Request

Description

Adds a --depth argument (default: 1, range: 1–6) that controls the markdown heading depth of the self-validation report and acts as the default value for --report-depth in publish mode when not explicitly specified.

Behavior:

• --depth N sets the self-validation heading to N hashes (e.g., --depth 2 → ## DEMA Consulting VersionMark)
• --depth N sets the default for --report-depth — explicit --report-depth always wins
• Default depth is 1, preserving current self-validation output (# DEMA Consulting VersionMark)
• Both --depth and --report-depth are validated to the range 1–6 (matching Markdown heading levels), with an ArgumentException thrown for out-of-range values

Example:

# Embed both self-validation and publish report at heading level 2
versionmark --depth 2 --validate
versionmark --depth 2 --publish --report versions.md   # --report-depth defaults to 2
versionmark --depth 2 --publish --report versions.md --report-depth 3  # explicit wins

Implementation highlights:

• Context.cs: Added Depth property; ArgumentParser.ReportDepth computed as _explicitReportDepth ?? Depth; both --depth and --report-depth validated to range 1–6
• Validation.cs: PrintValidationHeader derives heading prefix from context.Depth
• Program.cs: Help text updated for --depth and --report-depth showing range 1–6
• Default --report-depth changed from 2 → 1 (via --depth default); affected integration tests updated accordingly
• SelfTestTests.cs: Uses Validation.Run(context) directly instead of Program.Run(context) to respect subsystem hierarchy

Type of Change

• New feature (non-breaking change which adds functionality)

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.VersionMark --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:

• Spell checker passes: cspell "**/*.{md,cs}"
• Markdown linter passes: markdownlint "**/*.md"
• YAML linter passes: yamllint .

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

Context_Create_NoReportDepth_DefaultsToTwo renamed to Context_Create_NoReportDepth_DefaultsToDepthOne to reflect the new default. Integration tests expecting ## Tool Versions updated to # Tool Versions. Upper-bound tests Context_Create_DepthSeven_ThrowsArgumentException and Context_Create_ReportDepthSeven_ThrowsArgumentException added to cover the range 1–6 enforcement. SelfTest subsystem tests now call Validation.Run(context) directly rather than Program.Run(context) to comply with subsystem hierarchy rules.

[Copilot]

Pull request overview

This PR adds a new --depth CLI argument to control Markdown heading depth for self-validation output and to serve as the default for --report-depth in publish mode, updating documentation and tests accordingly.

Changes:

• Add Context.Depth (default 1) and make Context.ReportDepth default to Depth unless --report-depth is explicitly provided.
• Use context.Depth to control the self-validation report heading level.
• Update docs and tests to reflect the new default heading depth behavior.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/DemaConsulting.VersionMark/Cli/Context.cs	Adds Depth, changes ReportDepth defaulting behavior, and extends argument parsing.
src/DemaConsulting.VersionMark/Program.cs	Updates help output to include --depth and adjust --report-depth description.
src/DemaConsulting.VersionMark/SelfTest/Validation.cs	Uses context.Depth when printing the validation report heading.
test/DemaConsulting.VersionMark.Tests/Cli/ContextTests.cs	Adds coverage for --depth parsing and defaulting rules between Depth and ReportDepth.
test/DemaConsulting.VersionMark.Tests/SelfTest/SelfTestTests.cs	Adds a test verifying --depth affects the self-validation header level.
test/DemaConsulting.VersionMark.Tests/ProgramTests.cs	Updates expected default publish report heading from ## to #.
test/DemaConsulting.VersionMark.Tests/IntegrationTests.cs	Updates expected default publish report heading from ## to #.
README.md	Documents --depth and updates --report-depth default semantics.
docs/user_guide/guide.md	Documents --depth and updates publish examples/default semantics.
docs/design/version-mark/cli/context.md	Updates design table to include Depth and new ReportDepth defaulting.
docs/reqstream/version-mark/cli/context.yaml	Adds new/renamed test method references for the Context depth behavior.
docs/reqstream/version-mark/self-test/validation.yaml	Adds requirement/test mapping for depth-controlled validation header.

Comments suppressed due to low confidence (1)

src/DemaConsulting.VersionMark/Cli/Context.cs:405

• Same concern for --depth: it is unbounded above, but is used to construct Markdown heading prefixes. Please add an upper-bound validation (e.g., 6) or clamp the value to avoid pathological allocations / invalid Markdown output.

                case "--depth":
                    Depth = GetRequiredIntArgument(arg, args, index, "a depth value");
                    if (Depth < 1)
                    {
                        throw new ArgumentException($"{arg} requires a positive integer value (minimum 1)", nameof(args));
                    }

                    return index + 1;

---

💡 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