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
@@ -20,12 +20,12 @@ namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Integration.Infrastructure;
 /// </summary>
 /// <remarks>
 /// <para>
-/// Production wiring keeps the wire push deferred to M6 — the site SQLite hot
-/// path is the source of truth and a future M6 drain will push the rows
+/// Production wiring keeps the wire push deferred — the site SQLite hot
+/// path is the source of truth and a future drain will push the rows
 /// through the gRPC client. For end-to-end testing today we need a way to
 /// exercise the central dual-write transaction immediately, so this
 /// dispatcher synthesises the wire packet inline and round-trips it through
-/// the stub client. The shape mirrors what the M6 drain will eventually emit.
+/// the stub client. The shape mirrors what the future drain will eventually emit.
 /// </para>
 /// <para>
 /// <b>Best-effort:</b> both the inner forwarder call and the wire push are
@@ -40,6 +40,9 @@ public sealed class CombinedTelemetryDispatcher : ICachedCallTelemetryForwarder
    private readonly ICachedCallTelemetryForwarder _inner;
    private readonly ISiteStreamAuditClient _wireClient;

+    /// <summary>Initializes the dispatcher with the inner forwarder and the wire client.</summary>
+    /// <param name="inner">The forwarder that handles site-local telemetry.</param>
+    /// <param name="wireClient">The client used to push audit rows over the wire.</param>
    public CombinedTelemetryDispatcher(
        ICachedCallTelemetryForwarder inner,
        ISiteStreamAuditClient wireClient)
@@ -48,7 +51,8 @@ public sealed class CombinedTelemetryDispatcher : ICachedCallTelemetryForwarder
        _wireClient = wireClient ?? throw new ArgumentNullException(nameof(wireClient));
    }

-    /// <inheritdoc/>
+    // Forwards the telemetry through the inner forwarder and then pushes its audit rows to the wire client.
+    /// <inheritdoc />
    public async Task ForwardAsync(CachedCallTelemetry telemetry, CancellationToken ct = default)
    {
        ArgumentNullException.ThrowIfNull(telemetry);
@@ -67,7 +71,7 @@ public sealed class CombinedTelemetryDispatcher : ICachedCallTelemetryForwarder
        }

        // Project the same packet onto the wire and push it through the stub
-        // client. This is the bit a future M6 drain will subsume — until
+        // client. This is the bit a future drain will subsume — until
        // then the test wraps the two halves into one observer-driven step.
        try
        {
@@ -79,7 +83,7 @@ public sealed class CombinedTelemetryDispatcher : ICachedCallTelemetryForwarder
        {
            // Swallow — the audit row is still in SQLite for a future drain;
            // the central row will materialise the next time the wire path
-            // is exercised (or via the M6 reconciliation pull).
+            // is exercised (or via the reconciliation pull).
        }
    }

@@ -21,7 +21,7 @@ using ZB.MOM.WW.ScadaBridge.SiteRuntime.Tracking;
 namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Integration.Infrastructure;

 /// <summary>
-/// Shared end-to-end harness for the M3 cached-call combined telemetry tests
+/// Shared end-to-end harness for the cached-call combined telemetry tests
 /// (G2/G3/G4). Composes the full pipeline:
 /// <list type="bullet">
 ///   <item><description>Site-local SQLite <see cref="SqliteAuditWriter"/> (in-memory) +
@@ -48,15 +48,25 @@ namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Integration.Infrastructure;
 /// </remarks>
 public sealed class CombinedTelemetryHarness : IAsyncDisposable
 {
+    /// <summary>The site SQLite audit writer under test.</summary>
    public SqliteAuditWriter SqliteWriter { get; }
+    /// <summary>The in-memory ring buffer fallback for audit events.</summary>
    public RingBufferFallback Ring { get; }
+    /// <summary>The fallback audit writer that wraps the SQLite writer and the ring buffer.</summary>
    public FallbackAuditWriter FallbackWriter { get; }
+    /// <summary>The site-local operation tracking store.</summary>
    public OperationTrackingStore TrackingStore { get; }
+    /// <summary>The inner cached-call telemetry forwarder.</summary>
    public CachedCallTelemetryForwarder InnerForwarder { get; }
+    /// <summary>The combined telemetry dispatcher that sends audit and operational state together.</summary>
    public CombinedTelemetryDispatcher Dispatcher { get; }
+    /// <summary>The cached-call lifecycle bridge wired to the forwarder.</summary>
    public CachedCallLifecycleBridge Bridge { get; }
+    /// <summary>The stub site-stream audit client that delivers packets directly to the ingest actor.</summary>
    public DirectActorSiteStreamAuditClient StubClient { get; }
+    /// <summary>The central audit ingest actor.</summary>
    public IActorRef IngestActor { get; }
+    /// <summary>The service provider backing the central repositories.</summary>
    public IServiceProvider ServiceProvider { get; }

    private readonly MsSqlMigrationFixture _fixture;
@@ -64,6 +74,10 @@ public sealed class CombinedTelemetryHarness : IAsyncDisposable
    private readonly ServiceProvider _trackingLocalDbProvider;
    private bool _disposed;

+    /// <summary>Builds the harness, wiring the site writer chain, dispatcher and central ingest actor against the shared fixture.</summary>
+    /// <param name="fixture">The MS SQL migration fixture providing the central database.</param>
+    /// <param name="testKit">The Akka test kit that hosts the ingest actor.</param>
+    /// <param name="siteCallRepoOverride">Optional factory that replaces the default site-call audit repository.</param>
    public CombinedTelemetryHarness(
        MsSqlMigrationFixture fixture,
        Akka.TestKit.Xunit2.TestKit testKit,
@@ -133,15 +147,23 @@ public sealed class CombinedTelemetryHarness : IAsyncDisposable
    /// dispatcher (the bridge's hooks fire only for S&amp;F retry-loop
    /// attempts; submit-row emission happens at the script call site).
    /// </summary>
+    /// <param name="submit">The submit packet to forward.</param>
+    /// <param name="ct">A token to cancel the forward.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public Task EmitSubmitAsync(CachedCallTelemetry submit, CancellationToken ct = default) =>
        Dispatcher.ForwardAsync(submit, ct);

    /// <summary>
    /// Convenience: route a per-attempt or terminal outcome through the bridge.
    /// </summary>
+    /// <param name="context">The attempt or terminal-outcome context to route.</param>
+    /// <param name="ct">A token to cancel the emit.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public Task EmitAttemptAsync(CachedCallAttemptContext context, CancellationToken ct = default) =>
        Bridge.OnAttemptCompletedAsync(context, ct);

+    /// <summary>Creates a fresh central database context for reading back persisted rows.</summary>
+    /// <returns>A new <see cref="ScadaBridgeDbContext"/>.</returns>
    public ScadaBridgeDbContext CreateReadContext()
    {
        var options = new DbContextOptionsBuilder<ScadaBridgeDbContext>()
@@ -173,6 +195,8 @@ public sealed class CombinedTelemetryHarness : IAsyncDisposable
        return services.BuildServiceProvider();
    }

+    /// <summary>Releases the resources held by this test class asynchronously.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public async ValueTask DisposeAsync()
    {
        if (_disposed) return;
@@ -12,8 +12,8 @@ namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Integration.Infrastructure;
 /// Shared component-level <see cref="ISiteStreamAuditClient"/> test double that
 /// short-circuits the gRPC wire and forwards each batch directly to a central
 /// <see cref="AuditLog.Central.AuditLogIngestActor"/> via Akka <see cref="Futures.Ask"/>.
-/// Lives under <c>Integration/Infrastructure/</c> so both the M2 sync-call and
-/// M3 cached-call end-to-end suites can reuse it.
+/// Lives under <c>Integration/Infrastructure/</c> so both the sync-call and
+/// cached-call end-to-end suites can reuse it.
 /// </summary>
 /// <remarks>
 /// <para>
@@ -27,8 +27,8 @@ namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Integration.Infrastructure;
 /// </para>
 /// <para>
 /// <see cref="FailNextCallCount"/> arms a deterministic number of failures
-/// before the stub recovers; it applies to BOTH RPCs because the M2 sync-call
-/// retry behaviour and the M3 cached-telemetry retry behaviour share a single
+/// before the stub recovers; it applies to BOTH RPCs because the sync-call
+/// retry behaviour and the cached-telemetry retry behaviour share a single
 /// SiteAuditTelemetryActor drain. Tests that need to differentiate per-RPC
 /// failures should reach for a per-test wrapper rather than extending this
 /// shared infrastructure.
@@ -41,6 +41,8 @@ public sealed class DirectActorSiteStreamAuditClient : ISiteStreamAuditClient
    private int _callCount;
    private int _cachedTelemetryCallCount;

+    /// <summary>Initializes the client with the central ingest actor that receives every forwarded batch.</summary>
+    /// <param name="ingestActor">The central <c>AuditLogIngestActor</c> reference batches are asked of.</param>
    public DirectActorSiteStreamAuditClient(IActorRef ingestActor)
    {
        _ingestActor = ingestActor ?? throw new ArgumentNullException(nameof(ingestActor));
@@ -69,6 +71,7 @@ public sealed class DirectActorSiteStreamAuditClient : ISiteStreamAuditClient
    /// </summary>
    public int CachedTelemetryCallCount => Volatile.Read(ref _cachedTelemetryCallCount);

+    /// <inheritdoc />
    public async Task<IngestAck> IngestAuditEventsAsync(AuditEventBatch batch, CancellationToken ct)
    {
        Interlocked.Increment(ref _callCount);
@@ -106,18 +109,11 @@ public sealed class DirectActorSiteStreamAuditClient : ISiteStreamAuditClient
        return ack;
    }

-    /// <summary>
-    /// M3 dual-write path: decode each <see cref="CachedTelemetryPacket"/> into
-    /// the paired (<see cref="AuditEvent"/>, <see cref="SiteCall"/>) entry and
-    /// Ask the central ingest actor with an <see cref="IngestCachedTelemetryCommand"/>.
-    /// The accepted EventIds returned by the actor's dual-write transaction map
-    /// back into the proto ack.
-    /// </summary>
-    /// <remarks>
-    /// Uses the shared <see cref="AuditEventDtoMapper.FromDto"/> for the audit half
-    /// and <see cref="SiteCallDtoMapper.FromDto"/> for the SiteCall half — the same
-    /// canonical mappers the production <c>SiteStreamGrpcServer</c> uses.
-    /// </remarks>
+    // Dual-write path: decodes each CachedTelemetryPacket into the paired (AuditEvent, SiteCall)
+    // entry via the shared AuditEventDtoMapper.FromDto and SiteCallDtoMapper.FromDto (the same
+    // canonical mappers the production SiteStreamGrpcServer uses), then Asks the central ingest
+    // actor with an IngestCachedTelemetryCommand; the accepted EventIds map back into the proto ack.
+    /// <inheritdoc />
    public async Task<IngestAck> IngestCachedTelemetryAsync(CachedTelemetryBatch batch, CancellationToken ct)
    {
        Interlocked.Increment(ref _cachedTelemetryCallCount);