coverlet.console: add trace diagnostics and actionable warnings for instrumentation/hit/empty-result failures

[Bertk]

Summary

This PR improves troubleshooting in coverlet.console when coverage output is empty or unexpectedly 0% (especially in CI-only repros).
It adds:

• Trace verbosity support.
• --diag option to write detailed diagnostics to file.
• Better warning/error reporting across:

1. instrumentation eligibility/failures,
2. no-hit scenarios,
3. empty coverage result scenarios.

Problem

coverlet.console can complete successfully while producing an empty coverage report (no modules) or all-zero results, with limited diagnostics.
In CI, this is hard to root-cause because skipped instrumentation and missing-hit conditions are not summarized clearly.

Changes

1. coverlet.console trace diagnostics
   • Extended LogLevel with Trace.
   • Updated CLI verbosity help to include trace.
   • Added --diag option in Program:
   • writes timestamped diagnostics to file,
   • useful for CI artifact collection,
   • does not break normal console behavior.

2. Console logger enhancements
   • Added diagnostic file sink support (EnableDiagnosticFile).
   • Added trace logging method usage path (file + console depending on level).
   • Preserved existing thread-safe console output behavior.

3. Instrumentation diagnostics improvements (coverlet.core)
   • Added reason-aware CanInstrument(out string reason) overload in Instrumenter.
   • Coverage.PrepareModules() now logs explicit skip reasons and aggregates:
   • skipped not eligible,
   • skipped preflight,
   • instrumentation exceptions.
   • Added warning when selected modules exist but none are instrumented.

4. Hit collection and empty-result diagnostics
   • Coverage.CalculateCoverage() now tracks modules with non-zero hits.
   • Added warning when instrumented modules exist but no hits are collected.
   • Coverage.GetCoverageResult() now warns when final CoverageResult.Modules is empty and includes context counts.

5. Documentation update
   • Updated Documentation/GlobalTool.md:
   • Trace verbosity listed in options.
   • --diag option documented.
   • Added troubleshooting guidance for:
   • instrumentation failures,
   • no-hit runs,
   • empty coverage result output.

Why this helps

With this PR, CI logs (and optional diag artifacts) provide direct guidance instead of silent/ambiguous 0% output.
This reduces time-to-diagnose for environment-specific instrumentation and coverage collection issues.

Backward Compatibility

• Default behavior remains unchanged.
• Existing command lines continue to work.
• New diagnostics are additive.
• No breaking exit-code changes introduced.

Example usage

coverlet "<test_bin_dir>" `
  --target "dotnet" `
  --targetargs "<test_dll_path>" `
  --output "<results>\coverage.coverlet-console.json" `
  --verbosity trace `
  --diag "<results>\coverlet.console.trace.log"

[Copilot]

Pull request overview

This pull request enhances Coverlet’s troubleshooting experience when coverlet.console produces empty/0% coverage by adding trace verbosity, an optional diagnostic log file sink, and more actionable warnings in the instrumentation and hit-collection pipeline.

Changes:

• Added Trace verbosity and a --diag <path> option to persist detailed diagnostics to a file from coverlet.console.
• Improved instrumentation diagnostics in coverlet.core by logging skip reasons, aggregating instrumentation outcomes, and warning on “no instrumented modules” / “no hits” / “empty result modules”.
• Updated CI/test scripts, tool/workflow versions, and global tool documentation to reflect the new diagnostics capabilities.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/coverlet.core/Instrumentation/Instrumenter.cs	Adds CanInstrument(out reason) for reason-aware eligibility checks and improved diagnostics.
src/coverlet.core/Coverage.cs	Aggregates instrumentation outcomes; warns on no hits and empty module results.
src/coverlet.console/Program.cs	Adds --diag CLI option and wires it into the console logger.
src/coverlet.console/Logging/LogLevel.cs	Introduces Trace log level.
src/coverlet.console/Logging/ConsoleLogger.cs	Adds diagnostic file sink and a trace logging path.
scripts/test.ps1	Updates test runner progress option usage.
global.json	Bumps .NET SDK version.
Documentation/GlobalTool.md	Documents trace verbosity and --diag, adds troubleshooting guidance.
.github/workflows/issue-label-close.yml	Bumps actions/stale version.
.github/workflows/dotnet.yml	Bumps action versions used in CI and ReportGenerator/sticky-comment steps.
.github/workflows/codeql.yml	Pins CodeQL action versions and bumps setup-dotnet action.
.github/workflows/benchmark.yml	Bumps setup-dotnet action.
.config/dotnet-tools.json	Bumps reportgenerator tool version.