docs(tests): fix CommentChecker findings across tests/ — 13,392 → 0 (repo-wide scan clean)

Comment/XML-doc changes only: - add summaries to ~10k test methods, fixtures, fakes and helpers (+ <param> on theories, <returns> on async Task methods, <inheritdoc/> on interface implementations the checker can resolve) - strip ~2.6k project-tracking references (WP*, P*-*, row-NN, Task N, #NN, Component-0NN) from comments, keeping the explanatory text; reword false positives in comments only - real docs on fakes implementing BCL/library interfaces (IDisposable, ILogger, IOptionsMonitor, IAsyncLifetime) - reword the last 5 src/ false positives (CWE-1236, failures-1, year-0001, M365) Only non-comment edits: four one-line nested classes split across lines so members can carry docs. Build 0 errors / 0 warnings.
2026-10-07 15:05:49 -04:00
parent 0ffd4bdbea
commit 513fa1aa16
998 changed files with 17896 additions and 2395 deletions
@@ -13,7 +13,7 @@ using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
 namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Configuration;

 /// <summary>
-/// Bundle D (M5-T8) tests for hot-reloadable <see cref="AuditLogOptions"/>
+/// Tests for hot-reloadable <see cref="AuditLogOptions"/>
 /// binding. The first test pins the JSON-realistic binding shape end-to-end
 /// (scalars, lists, per-target overrides) so accidental drift in the section
 /// layout breaks the build. The second test exercises the live hot-reload
@@ -23,13 +23,14 @@ namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Configuration;
 /// flowing through without a restart.
 /// </summary>
 /// <remarks>
-/// Distinct from <see cref="AuditLogOptionsTests"/> (M1-T9) which covered
+/// Distinct from <see cref="AuditLogOptionsTests"/> which covered
 /// section binding + validator failures via single-key in-memory config — those
 /// tests exist; these add (a) end-to-end binding from a realistic JSON literal
-/// and (b) the hot-reload behavioural contract the M5-T8 spec calls out.
+/// and (b) the hot-reload behavioural contract the spec calls out.
 /// </remarks>
 public class AuditLogOptionsBindingTests
 {
+    /// <summary>Verifies that the AuditLog configuration section binds every field.</summary>
    [Fact]
    public void AuditLog_Section_Binds_AllFields()
    {
@@ -71,7 +72,7 @@ public class AuditLogOptionsBindingTests

        // HeaderRedactList: the Microsoft.Extensions.Configuration list binder
        // APPENDS to the default list, so we assert containment rather than
-        // exact equality (see M1-T9 AuditLogOptionsTests for the rationale).
+        // exact equality (see AuditLogOptionsTests for the rationale).
        Assert.Contains("Authorization", opts.HeaderRedactList);
        Assert.Contains("Custom-Token", opts.HeaderRedactList);

@@ -90,10 +91,11 @@ public class AuditLogOptionsBindingTests
        Assert.Equal("@token|@secret", ov.RedactSqlParamsMatching);
    }

+    /// <summary>Verifies that the purge options bind from the documented section and keys.</summary>
    [Fact]
    public void PurgeOptions_Bind_FromDocumentedSectionAndKeys()
    {
-        // AuditLog-013: the design doc (Component-AuditLog.md §Configuration)
+        // The design doc (Component-AuditLog.md §Configuration)
        // documents the purge tuning as the nested `AuditLog:Purge` section with
        // keys `IntervalHours` + `ChannelPurgeBatchSize`. This test pins that the
        // code binds from EXACTLY that shape — the section path the production
@@ -139,6 +141,7 @@ public class AuditLogOptionsBindingTests
        Assert.Equal(1000, opts.ChannelPurgeBatchSize);
    }

+    /// <summary>Verifies that the filter behavior updates when the configuration reloads.</summary>
    [Fact]
    public void Filter_Behavior_Updates_OnConfigReload()
    {
@@ -165,7 +168,7 @@ public class AuditLogOptionsBindingTests
        Assert.True(Encoding.UTF8.GetByteCount(resultBefore.AsRow().RequestSummary!) <= 4096);

        // Reload: cap raised to 16384 — next event must NOT truncate. This is
-        // the M5-T8 contract: the filter sees the new value on the very next
+        // the hot-reload contract: the filter sees the new value on the very next
        // Apply, without process restart.
        monitor.Set(new AuditLogOptions { DefaultCapBytes = 16384 });

@@ -174,6 +177,7 @@ public class AuditLogOptionsBindingTests
        Assert.Equal(body, resultAfter.AsRow().RequestSummary);
    }

+    /// <summary>Verifies that the filter picks up a new body redactor when the configuration reloads.</summary>
    [Fact]
    public void Filter_PicksUp_NewBodyRedactor_OnConfigReload()
    {
@@ -219,12 +223,21 @@ public class AuditLogOptionsBindingTests
        private T _current;
        private readonly List<Action<T, string?>> _listeners = new();

+        /// <summary>Initializes a new instance of the <c>TestOptionsMonitor</c> class.</summary>
+        /// <param name="initial">The initial.</param>
        public TestOptionsMonitor(T initial) => _current = initial;

+        /// <summary>Gets the current value value.</summary>
        public T CurrentValue => _current;

+        /// <summary>Returns the current options value regardless of the name.</summary>
+        /// <param name="name">The options name; ignored.</param>
+        /// <returns>The current options value.</returns>
        public T Get(string? name) => _current;

+        /// <summary>Registers a listener to be notified when the options change.</summary>
+        /// <param name="listener">The change callback.</param>
+        /// <returns>A disposable that removes the listener, or null when none is tracked.</returns>
        public IDisposable? OnChange(Action<T, string?> listener)
        {
            lock (_listeners)
@@ -234,6 +247,8 @@ public class AuditLogOptionsBindingTests
            return new Unsubscribe(_listeners, listener);
        }

+        /// <summary>Replaces the current value and notifies registered listeners.</summary>
+        /// <param name="value">The value.</param>
        public void Set(T value)
        {
            _current = value;
@@ -252,11 +267,15 @@ public class AuditLogOptionsBindingTests
        {
            private readonly List<Action<T, string?>> _listeners;
            private readonly Action<T, string?> _listener;
+            /// <summary>Initializes a new instance of the <c>Unsubscribe</c> class.</summary>
+            /// <param name="listeners">The listeners.</param>
+            /// <param name="listener">The listener.</param>
            public Unsubscribe(List<Action<T, string?>> listeners, Action<T, string?> listener)
            {
                _listeners = listeners;
                _listener = listener;
            }
+            /// <summary>Releases the resources held by the test fixture.</summary>
            public void Dispose()
            {
                lock (_listeners)
@@ -6,8 +6,8 @@ using ZB.MOM.WW.ScadaBridge.AuditLog.Configuration;
 namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Configuration;

 /// <summary>
-/// Task 9 (Bundle E): <see cref="AuditLogOptions"/> binding + validator
-/// behavior. The validator enforces invariants used by M2+ writers
+/// Tests for <see cref="AuditLogOptions"/> binding and validator
+/// behavior. The validator enforces invariants used by the audit writers
 /// (per <c>docs/plans/2026-05-20-auditlog-m1-foundation.md</c>):
 /// <c>DefaultCapBytes &gt; 0</c>, <c>ErrorCapBytes &gt;= DefaultCapBytes</c>,
 /// <c>RetentionDays in [30, 3650]</c>. Header-redact defaults match the
@@ -25,6 +25,7 @@ public class AuditLogOptionsTests
        return services.BuildServiceProvider().GetRequiredService<IOptions<AuditLogOptions>>();
    }

+    /// <summary>Verifies that a fully populated configuration section binds every scalar field onto the options.</summary>
    [Fact]
    public void ValidBinding_PopulatesAllScalarFields()
    {
@@ -40,6 +41,7 @@ public class AuditLogOptionsTests
        Assert.Equal(180, opts.RetentionDays);
    }

+    /// <summary>Verifies that an empty configuration section yields reasonable default option values.</summary>
    [Fact]
    public void DefaultsAreReasonable_WhenSectionEmpty()
    {
@@ -56,6 +58,7 @@ public class AuditLogOptionsTests
        Assert.Empty(opts.PerTargetOverrides);
    }

+    /// <summary>Verifies that header redaction entries bound from configuration are appended to the default list.</summary>
    [Fact]
    public void HeaderRedactList_BindsFromConfig_AppendsToDefaults()
    {
@@ -77,6 +80,7 @@ public class AuditLogOptionsTests
        Assert.Contains("X-Api-Key", opts.HeaderRedactList);
    }

+    /// <summary>Verifies that per-target override settings bind from configuration.</summary>
    [Fact]
    public void PerTargetOverrides_BindsFromConfig()
    {
@@ -93,6 +97,7 @@ public class AuditLogOptionsTests
        Assert.Contains(@"\d{16}", crm.AdditionalBodyRedactors!);
    }

+    /// <summary>Verifies that an invalid default payload cap fails validation.</summary>
    [Fact]
    public void InvalidDefaultCapBytes_FailsValidation()
    {
@@ -104,6 +109,7 @@ public class AuditLogOptionsTests
        Assert.Contains("DefaultCapBytes", result.FailureMessage);
    }

+    /// <summary>Verifies that an invalid error payload cap fails validation.</summary>
    [Fact]
    public void InvalidErrorCapBytes_FailsValidation()
    {
@@ -115,6 +121,7 @@ public class AuditLogOptionsTests
        Assert.Contains("ErrorCapBytes", result.FailureMessage);
    }

+    /// <summary>Verifies that a retention period below the minimum fails validation.</summary>
    [Fact]
    public void RetentionDaysBelowMinimum_FailsValidation()
    {
@@ -126,6 +133,7 @@ public class AuditLogOptionsTests
        Assert.Contains("RetentionDays", result.FailureMessage);
    }

+    /// <summary>Verifies that a retention period above the maximum fails validation.</summary>
    [Fact]
    public void RetentionDaysAboveMaximum_FailsValidation()
    {
@@ -137,6 +145,7 @@ public class AuditLogOptionsTests
        Assert.Contains("RetentionDays", result.FailureMessage);
    }

+    /// <summary>Verifies that the default options pass validation.</summary>
    [Fact]
    public void DefaultOptions_PassValidation()
    {
@@ -147,6 +156,7 @@ public class AuditLogOptionsTests
        Assert.True(result.Succeeded, result.FailureMessage);
    }

+    /// <summary>Verifies that an invalid retention value bound from configuration is rejected when the options value is accessed.</summary>
    [Fact]
    public void InvalidRetention_BoundViaConfig_RejectedOnValueAccess()
    {
@@ -3,7 +3,7 @@ using ZB.MOM.WW.ScadaBridge.AuditLog.Configuration;
 namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Configuration;

 /// <summary>
-/// Task 1 of <c>docs/plans/2026-05-23-inbound-api-full-response-audit.md</c>:
+/// Per <c>docs/plans/2026-05-23-inbound-api-full-response-audit.md</c>, this class
 /// pins the <see cref="AuditLogOptions.InboundMaxBytes"/> default to 1 MiB and
 /// the validator bounds to <c>[8 KiB, 16 MiB]</c>. The inbound channel needs a
 /// much larger ceiling than the 8 KiB / 64 KiB default/error caps that other
@@ -14,6 +14,7 @@ namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Configuration;
 /// </summary>
 public class AuditLogOptionsValidatorTests
 {
+    /// <summary>Verifies that the default options set the inbound maximum body size to one mebibyte.</summary>
    [Fact]
    public void Validate_InboundMaxBytes_DefaultOptions_IsOneMebibyte()
    {
@@ -24,6 +25,8 @@ public class AuditLogOptionsValidatorTests
        Assert.Equal(1_048_576, opts.InboundMaxBytes);
    }

+    /// <summary>Verifies that an inbound maximum body size within the documented range passes validation.</summary>
+    /// <param name="value">The inbound maximum body size in bytes.</param>
    [Theory]
    [InlineData(8_192)]              // documented min
    [InlineData(1_048_576)]          // default
@@ -35,6 +38,8 @@ public class AuditLogOptionsValidatorTests
        Assert.True(validator.Validate(null, opts).Succeeded);
    }

+    /// <summary>Verifies that an inbound maximum body size outside the documented range fails validation.</summary>
+    /// <param name="value">The inbound maximum body size in bytes.</param>
    [Theory]
    [InlineData(0)]
    [InlineData(8_191)]
@@ -52,9 +57,10 @@ public class AuditLogOptionsValidatorTests
    }

    // ---------------------------------------------------------------------
-    // M5.5 (T3) per-channel retention overrides
+    // Per-channel retention overrides
    // ---------------------------------------------------------------------

+    /// <summary>Verifies that a per-channel retention shorter than the global retention passes validation.</summary>
    [Fact]
    public void Validate_PerChannelRetention_ShorterThanGlobal_Passes()
    {
@@ -75,6 +81,7 @@ public class AuditLogOptionsValidatorTests
        Assert.True(validator.Validate(null, opts).Succeeded);
    }

+    /// <summary>Verifies that a per-channel retention equal to the global retention passes validation.</summary>
    [Fact]
    public void Validate_PerChannelRetention_EqualToGlobal_Passes()
    {
@@ -90,6 +97,7 @@ public class AuditLogOptionsValidatorTests
        Assert.True(validator.Validate(null, opts).Succeeded);
    }

+    /// <summary>Verifies that a per-channel retention longer than the global retention fails validation.</summary>
    [Fact]
    public void Validate_PerChannelRetention_LongerThanGlobal_Fails()
    {
@@ -110,6 +118,7 @@ public class AuditLogOptionsValidatorTests
                 && f.Contains("ApiInbound", StringComparison.Ordinal));
    }

+    /// <summary>Verifies that a per-channel retention below the minimum fails validation.</summary>
    [Fact]
    public void Validate_PerChannelRetention_BelowMinimum_Fails()
    {
@@ -127,6 +136,7 @@ public class AuditLogOptionsValidatorTests
            f => f.Contains(nameof(AuditLogOptions.PerChannelRetentionDays), StringComparison.Ordinal));
    }

+    /// <summary>Verifies that a per-channel retention keyed by an unknown channel fails validation.</summary>
    [Fact]
    public void Validate_PerChannelRetention_UnknownChannelKey_Fails()
    {
@@ -146,6 +156,7 @@ public class AuditLogOptionsValidatorTests
            f => f.Contains("NotAChannel", StringComparison.Ordinal));
    }

+    /// <summary>Verifies that the default empty per-channel retention map passes validation.</summary>
    [Fact]
    public void Validate_PerChannelRetention_DefaultEmpty_Passes()
    {