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
@@ -53,6 +53,8 @@ public class CachedCallLifecycleBridgeTests
            SourceScript: sourceScript,
            ParentExecutionId: parentExecutionId);

+    /// <summary>Verifies that a transient failure emits one Attempted row and no resolve row.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task TransientFailure_EmitsOneAttemptedRow_NoResolve()
    {
@@ -78,6 +80,8 @@ public class CachedCallLifecycleBridgeTests
        Assert.Null(packet.Operational.TerminalAtUtc);
    }

+    /// <summary>Verifies that a delivered attempt emits an Attempted row and a CachedResolve row with Delivered status.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Delivered_EmitsAttemptedRow_AndCachedResolveDelivered()
    {
@@ -104,6 +108,8 @@ public class CachedCallLifecycleBridgeTests
        Assert.Equal(_id.Value, resolve.Audit.AsRow().CorrelationId);
    }

+    /// <summary>Verifies that a permanent failure emits an Attempted row and a CachedResolve row with Parked status.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task PermanentFailure_EmitsAttempted_AndCachedResolveParked()
    {
@@ -123,6 +129,8 @@ public class CachedCallLifecycleBridgeTests
        Assert.Equal("Parked", captured[1].Operational.Status);
    }

+    /// <summary>Verifies that parking after the maximum retries emits an Attempted row and a CachedResolve row with Parked status.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task ParkedMaxRetries_EmitsAttempted_AndCachedResolveParked()
    {
@@ -138,6 +146,8 @@ public class CachedCallLifecycleBridgeTests
        Assert.Equal(AuditStatus.Parked, captured[1].Audit.AsRow().Status);
    }

+    /// <summary>Verifies that the database channel maps to the DbWriteCached kind and the DbOutbound channel.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task DbChannel_MapsToDbWriteCachedKind_AndDbOutboundChannel()
    {
@@ -157,6 +167,8 @@ public class CachedCallLifecycleBridgeTests
        Assert.Equal(AuditChannel.DbOutbound, captured[1].Audit.AsRow().Channel);
    }

+    /// <summary>Verifies that the bridge does not throw when the telemetry forwarder throws.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task BridgeDoesNotThrow_WhenForwarderThrows()
    {
@@ -170,6 +182,8 @@ public class CachedCallLifecycleBridgeTests
        await sut.OnAttemptCompletedAsync(Ctx(CachedCallAttemptOutcome.Delivered));
    }

+    /// <summary>Verifies that the bridge populates provenance fields from the attempt context.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task BridgePopulatesProvenance_FromAttemptContext()
    {
@@ -192,12 +206,14 @@ public class CachedCallLifecycleBridgeTests
        Assert.Equal(_id.Value, captured.Audit.AsRow().CorrelationId);
    }

-    // ── Audit Log #23 (ExecutionId Task 4): ExecutionId / SourceScript ──
+    // ── ExecutionId / SourceScript ──

+    /// <summary>Verifies that a retry-loop Attempted row carries the ExecutionId and SourceScript from the attempt context.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RetryLoopAttemptedRow_CarriesExecutionIdAndSourceScript_FromContext()
    {
-        // Task 4: the ExecutionId + SourceScript threaded through the S&F
+        // The ExecutionId + SourceScript threaded through the S&F
        // buffer arrive on the CachedCallAttemptContext; the bridge must stamp
        // both onto the per-attempt ApiCallCached row (previously SourceScript
        // was hard-coded null with a "not threaded through S&F" comment).
@@ -218,6 +234,8 @@ public class CachedCallLifecycleBridgeTests
        Assert.Equal("Plant.Pump42/OnTick", packet.Audit.AsRow().SourceScript);
    }

+    /// <summary>Verifies that a retry-loop CachedResolve row carries the ExecutionId and SourceScript from the attempt context.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RetryLoopCachedResolveRow_CarriesExecutionIdAndSourceScript_FromContext()
    {
@@ -245,10 +263,12 @@ public class CachedCallLifecycleBridgeTests
        Assert.Equal("Plant.Tank/OnAlarm", attempted.Audit.AsRow().SourceScript);
    }

+    /// <summary>Verifies that a retry-loop row leaves ExecutionId and SourceScript null when the context has none.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RetryLoopRow_NullExecutionIdAndSourceScript_RemainNull()
    {
-        // Back-compat: a pre-Task-4 buffered row has no ExecutionId /
+        // Back-compat: a buffered row written before ExecutionId was threaded through has no ExecutionId /
        // SourceScript; the bridge must leave the audit row's fields null
        // rather than throwing.
        CachedCallTelemetry? captured = null;
@@ -263,12 +283,14 @@ public class CachedCallLifecycleBridgeTests
        Assert.Null(captured.Audit.AsRow().SourceScript);
    }

-    // ── Audit Log #23 (ParentExecutionId Task 6): ParentExecutionId ──
+    // ── ParentExecutionId ──

+    /// <summary>Verifies that a retry-loop Attempted row carries the ParentExecutionId from the attempt context.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RetryLoopAttemptedRow_CarriesParentExecutionId_FromContext()
    {
-        // Task 6: the ParentExecutionId threaded through the S&F buffer (the
+        // The ParentExecutionId threaded through the S&F buffer (the
        // inbound-API run that spawned the originating script) arrives on the
        // CachedCallAttemptContext; the bridge must stamp it onto the
        // per-attempt ApiCallCached row beside ExecutionId.
@@ -287,6 +309,8 @@ public class CachedCallLifecycleBridgeTests
        Assert.Equal(parentExecutionId, packet.Audit.AsRow().ParentExecutionId);
    }

+    /// <summary>Verifies that a retry-loop CachedResolve row carries the ParentExecutionId from the attempt context.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RetryLoopCachedResolveRow_CarriesParentExecutionId_FromContext()
    {
@@ -312,6 +336,8 @@ public class CachedCallLifecycleBridgeTests
        Assert.Equal(parentExecutionId, attempted.Audit.AsRow().ParentExecutionId);
    }

+    /// <summary>Verifies that a retry-loop row leaves ParentExecutionId null when the context has none.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RetryLoopRow_NullParentExecutionId_RemainsNull()
    {
@@ -329,12 +355,14 @@ public class CachedCallLifecycleBridgeTests
        Assert.Null(captured!.Audit.AsRow().ParentExecutionId);
    }

-    // ── SourceNode-stamping (Task 14) ──
+    // ── SourceNode stamping ──

+    /// <summary>Verifies that a retry-loop row stamps the source node name from the node identity provider.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RetryLoopRow_StampsSourceNode_FromNodeIdentityProvider()
    {
-        // SourceNode-stamping (Task 14): when an INodeIdentityProvider is
+        // SourceNode stamping: when an INodeIdentityProvider is
        // wired the bridge stamps the local node name (node-a/node-b) onto
        // the SiteCallOperational.SourceNode column of every emitted packet.
        var nodeIdentity = Substitute.For<INodeIdentityProvider>();
@@ -353,6 +381,8 @@ public class CachedCallLifecycleBridgeTests
        Assert.All(captured, p => Assert.Equal("node-a", p.Operational.SourceNode));
    }

+    /// <summary>Verifies that a retry-loop row leaves the source node null when no node identity provider is configured.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RetryLoopRow_NoNodeIdentityProvider_LeavesSourceNodeNull()
    {
@@ -371,6 +401,8 @@ public class CachedCallLifecycleBridgeTests
        Assert.Null(packet.Operational.SourceNode);
    }

+    /// <summary>Verifies that a retry-loop row leaves the source node null when the node identity has a null node name.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RetryLoopRow_NodeIdentityWithNullNodeName_LeavesSourceNodeNull()
    {