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
@@ -39,6 +39,7 @@ public class FlowDebugRunnerTests
    private readonly InboundScriptExecutor _executor = new(NullLogger<InboundScriptExecutor>.Instance, Substitute.For<IServiceProvider>());
    private DateTimeOffset _clock = new(2026, 9, 5, 12, 0, 0, TimeSpan.Zero);

+    /// <summary>Initializes a new instance of the <see cref="FlowDebugRunnerTests"/> class with an active-node gate and a fake audit writer.</summary>
    public FlowDebugRunnerTests()
    {
        _gate.IsActiveNode.Returns(true);
@@ -60,6 +61,9 @@ public class FlowDebugRunnerTests

    private static JsonElement Json(string s) => JsonDocument.Parse(s).RootElement.Clone();

+    /// <summary>Verifies that a late completion behind the log cursor is still found despite site clock skew.</summary>
+    /// <param name="skewSeconds">The offset of the site clock relative to central, in seconds.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Theory]
    [InlineData(0)]
    [InlineData(-3600)]
@@ -108,6 +112,8 @@ public class FlowDebugRunnerTests
        Assert.Equal(3, result.Events.Count);
    }

+    /// <summary>Verifies that a value-change run pages through ties and queries older descendants beyond 64 execution ids.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunValueChange_PagesTiesAndQueriesOlderDescendantsBeyond64Ids()
    {
@@ -159,6 +165,8 @@ public class FlowDebugRunnerTests
        Assert.All(grandchildren.Values, id => Assert.Contains(id, queried));
    }

+    /// <summary>Verifies that replay uses the chain anchor even when the child clock precedes the root.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Replay_UsesChainAnchorEvenWhenChildClockPrecedesRoot()
    {
@@ -173,6 +181,8 @@ public class FlowDebugRunnerTests
        Assert.Equal(root, result.RootExecutionId);
    }

+    /// <summary>Verifies that the total deadline of a value-change run includes the initial write.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunValueChange_TotalDeadlineIncludesInitialWrite()
    {
@@ -191,6 +201,8 @@ public class FlowDebugRunnerTests
        Assert.Empty(puller.ReceivedCalls());
    }

+    /// <summary>Verifies that the total deadline of a value-change run includes the audit write.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunValueChange_TotalDeadlineIncludesAuditWrite()
    {
@@ -207,6 +219,8 @@ public class FlowDebugRunnerTests
        Assert.Empty(puller.ReceivedCalls());
    }

+    /// <summary>Verifies that a value-change run caps the returned events and reports truncation.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunValueChange_CapsReturnedEventsAndReportsTruncation()
    {
@@ -220,6 +234,8 @@ public class FlowDebugRunnerTests
        Assert.InRange(result.Events.Count, 1, FlowTraceCollector.DefaultMaxEvents);
    }

+    /// <summary>Verifies that running a method on a standby node is refused with the standby code before the method is touched.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunMethod_OnStandby_RefusesWithStandbyCode_BeforeTouchingTheMethod()
    {
@@ -231,6 +247,8 @@ public class FlowDebugRunnerTests
        await _apiRepo.DidNotReceiveWithAnyArgs().GetApiMethodByIdAsync(default, default);
    }

+    /// <summary>Verifies that invalid method parameters fail before any route call is made.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunMethod_InvalidParameters_FailsBeforeAnyRouteCall()
    {
@@ -248,6 +266,8 @@ public class FlowDebugRunnerTests
        Assert.Empty(_central);
    }

+    /// <summary>Verifies that a successful method run returns the inbound row followed by the ordered sink events and writes the inbound row.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunMethod_HappyPath_ReturnsInboundRow_ThenSinkEvents_Ordered_AndWritesTheInboundRow()
    {
@@ -287,6 +307,8 @@ public class FlowDebugRunnerTests
        Assert.Contains(_central, e => e.AsRow().Kind == AuditKind.RouteCall);
    }

+    /// <summary>Verifies that a site clock behind central still returns the sink events in emission order.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunMethod_SiteClockBehindCentral_StillReturnsTheSinkEventsInEmissionOrder()
    {
@@ -312,6 +334,8 @@ public class FlowDebugRunnerTests
        Assert.Same(siteRun, result.Events[2]);
    }

+    /// <summary>Verifies that the inbound row carries the error detail when the method script throws.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunMethod_ScriptThrows_InboundRowCarriesErrorDetail()
    {
@@ -336,6 +360,8 @@ public class FlowDebugRunnerTests
        Assert.StartsWith("System.InvalidOperationException: boom", returnedInbound.ErrorDetail);
    }

+    /// <summary>Verifies that running an unknown method reports not found.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunMethod_UnknownMethod_IsNotFound()
    {
@@ -359,6 +385,8 @@ public class FlowDebugRunnerTests
        return (templates, sites, puller);
    }

+    /// <summary>Verifies that a traced value-change write is followed by polling until the spawned run settles.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunValueChange_TracedWrite_ThenPollsUntilSpawnedRunSettles()
    {
@@ -396,6 +424,8 @@ public class FlowDebugRunnerTests
        Assert.True(calls >= 3, $"expected settle polls, got {calls}");
    }

+    /// <summary>Verifies that a value-change run reports the no-trigger code when no run is spawned within the window.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunValueChange_NoSpawnWithinWindow_ReportsNoTriggerCode()
    {
@@ -410,6 +440,8 @@ public class FlowDebugRunnerTests
        Assert.Single(result.Events); // just the synthesized write row
    }

+    /// <summary>Verifies that a value-change run asks the site for its full page of rows rather than the old 500-row cap.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunValueChange_AsksTheSiteForItsFullPage_NotTheOldFiveHundredRowCap()
    {
@@ -431,6 +463,8 @@ public class FlowDebugRunnerTests
        Assert.Equal(2000, FlowDebugRunner.PullTraceEventsMax);
    }

+    /// <summary>Verifies that a value-change run against an out-of-scope site is refused.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunValueChange_OutOfScopeSite_IsRefused()
    {
@@ -441,6 +475,8 @@ public class FlowDebugRunnerTests
        await _router.DidNotReceiveWithAnyArgs().RouteToSetAttributesAsync(default!, default!, default);
    }

+    /// <summary>Verifies that replay threads the site scope through and retains a truncated root that has no rows.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Replay_ThreadsScopeAndRetainsTruncatedRootWithoutRows()
    {
@@ -453,6 +489,8 @@ public class FlowDebugRunnerTests
        Assert.True(result.Completed); Assert.True(result.Truncated); Assert.Equal(root, result.RootExecutionId);
    }

+    /// <summary>Verifies that replay returns the repository rows with the root taken from the first row.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Replay_ReturnsRepositoryRows_WithRootFromTheFirstRow()
    {
@@ -504,6 +542,8 @@ public class FlowDebugRunnerTests
        return sites;
    }

+    /// <summary>Verifies that a site-scoped deployer routing to another site is unauthorized and the inbound row is still written.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunMethod_ScopedDeployer_RouteToOtherSite_IsUnauthorized_AndInboundRowIsWritten()
    {
@@ -519,6 +559,8 @@ public class FlowDebugRunnerTests
        Assert.Contains(_central, e => e.AsRow().Kind == AuditKind.InboundRequest && e.Actor == "ops");
    }

+    /// <summary>Verifies that a site-scoped deployer routing within its scope runs the method.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunMethod_ScopedDeployer_RouteWithinScope_Runs()
    {
@@ -533,6 +575,8 @@ public class FlowDebugRunnerTests
        await _router.ReceivedWithAnyArgs(1).RouteToCallAsync(default!, default!, default);
    }

+    /// <summary>Verifies that an administrator is never restricted by site scope.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunMethod_Administrator_IsNeverScoped()
    {
@@ -546,6 +590,8 @@ public class FlowDebugRunnerTests
        await _router.ReceivedWithAnyArgs(1).RouteToCallAsync(default!, default!, default);
    }

+    /// <summary>Verifies that a user without site scoping is never restricted by site scope.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunMethod_UnscopedUser_IsNeverScoped()
    {
@@ -559,6 +605,7 @@ public class FlowDebugRunnerTests
        await _router.ReceivedWithAnyArgs(1).RouteToCallAsync(default!, default!, default);
    }

+    /// <summary>Verifies that the three run commands are restricted to the Deployer role.</summary>
    [Fact]
    public void RoleGate_TheThreeRunCommands_AreDeployerOnly()
    {
@@ -572,6 +619,7 @@ public class FlowDebugRunnerTests
            Assert.Equal(new[] { "Deployer" }, ManagementActor.GetRequiredRoles(cmd));
    }

+    /// <summary>Verifies that replay also accepts the operational audit roles.</summary>
    [Fact]
    public void RoleGate_Replay_AlsoAcceptsTheOperationalAuditRoles()
    {
@@ -612,6 +660,8 @@ public class FlowDebugRunnerTests
            AuditChannel.ScriptTrace, AuditKind.ScriptLog, AuditStatus.Delivered,
            executionId: Guid.NewGuid(), target: "work");

+    /// <summary>Verifies that sink events are redacted when a redactor is registered.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunMethod_SinkEvents_AreRedacted_WhenARedactorIsRegistered()
    {
@@ -632,6 +682,8 @@ public class FlowDebugRunnerTests
        Assert.NotEqual(written.DetailsJson, result.Events[0].DetailsJson); // the raw row still reaches the writer
    }

+    /// <summary>Verifies that the synthesized root row of a value-change run is redacted when a redactor is registered.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunValueChange_SynthesizedRootRow_IsRedacted_WhenARedactorIsRegistered()
    {
@@ -648,6 +700,8 @@ public class FlowDebugRunnerTests
        Assert.NotEqual(written.DetailsJson, root.DetailsJson);
    }

+    /// <summary>Verifies that a failed value-change write returns the redacted root row.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunValueChange_FailedWrite_ReturnsTheRedactedRootRow()
    {
@@ -667,6 +721,8 @@ public class FlowDebugRunnerTests
        Assert.NotEqual(written.DetailsJson, root.DetailsJson);
    }

+    /// <summary>Verifies that a method run over the event cap reports truncation.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunMethod_OverCap_ReportsTruncated()
    {
@@ -680,6 +736,8 @@ public class FlowDebugRunnerTests
        Assert.False(result.LogsTruncated); // these are full-priority step rows, not log lines
    }

+    /// <summary>Verifies that a method run with no log rows does not report truncated logs.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunMethod_NoLogRows_LogsTruncatedIsFalse()
    {
@@ -693,6 +751,8 @@ public class FlowDebugRunnerTests
        Assert.False(result.Truncated);
    }

+    /// <summary>Verifies that exceeding the low-priority reserve reports truncated logs but not truncated events.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunMethod_OverLowPriorityReserve_ReportsLogsTruncated_ButNotTruncated()
    {
@@ -736,6 +796,8 @@ public class FlowDebugRunnerTests
    private static ResolvedScript WriteScript(string name, string kind, string attribute) =>
        new() { CanonicalName = name, Code = "return 1;", TriggerType = kind, TriggerConfiguration = $$"""{"attributeName":"{{attribute}}"}""" };

+    /// <summary>Verifies that a write-kind script run writes the trigger attribute and then polls for completion.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunScript_WriteKind_WritesTheTriggerAttribute_ThenPolls()
    {
@@ -773,6 +835,8 @@ public class FlowDebugRunnerTests
        await _router.DidNotReceiveWithAnyArgs().RouteToCallAsync(default!, default!, default);
    }

+    /// <summary>Verifies that running a script on a standby node is refused with the standby code before the instance is touched.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunScript_OnStandby_RefusesWithStandbyCode_BeforeTouchingTheInstance()
    {
@@ -788,6 +852,8 @@ public class FlowDebugRunnerTests
        await pipeline.DidNotReceiveWithAnyArgs().FlattenAndValidateAsync(default, default, default, default);
    }

+    /// <summary>Verifies that a write-kind script run with an unreadable trigger configuration fails validation.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunScript_WriteKind_UnreadableTriggerConfig_FailsValidation()
    {
@@ -806,6 +872,8 @@ public class FlowDebugRunnerTests
        await _router.DidNotReceiveWithAnyArgs().RouteToSetAttributesAsync(default!, default!, default);
    }

+    /// <summary>Verifies that a write-kind script run without a value fails validation before any write.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunScript_WriteKind_WithoutValue_FailsValidation_BeforeAnyWrite()
    {
@@ -816,6 +884,8 @@ public class FlowDebugRunnerTests
        await _router.DidNotReceiveWithAnyArgs().RouteToSetAttributesAsync(default!, default!, default);
    }

+    /// <summary>Verifies that a run of a sibling script does not count as completion of a write-kind script run.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunScript_WriteKind_SiblingScriptRun_DoesNotCountAsCompletion()
    {
@@ -838,6 +908,8 @@ public class FlowDebugRunnerTests
        Assert.Equal("OtherScript", result.Events[1].Target);
    }

+    /// <summary>Verifies that a call-kind script run routes a traced call and returns the root route-call row followed by the site rows.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunScript_CallKind_RoutesATracedCall_AndReturnsRootRouteCallRow_ThenSiteRows()
    {
@@ -875,6 +947,8 @@ public class FlowDebugRunnerTests
        Assert.Single(_central); // the root row was written centrally
    }

+    /// <summary>Verifies that a call-kind script run with invalid parameters fails before routing.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunScript_CallKind_InvalidParameters_FailsBeforeRouting()
    {
@@ -886,6 +960,8 @@ public class FlowDebugRunnerTests
        Assert.Empty(_central);
    }

+    /// <summary>Verifies that a site failure in a call-kind script run reports call failed with the root row.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunScript_CallKind_SiteFailure_ReportsCallFailed_WithTheRootRow()
    {
@@ -903,6 +979,8 @@ public class FlowDebugRunnerTests
        Assert.Equal(AuditStatus.Failed, result.Events[0].AsRow().Status);
    }

+    /// <summary>Verifies that running an unknown script reports not found.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunScript_UnknownScript_IsNotFound()
    {
@@ -913,6 +991,8 @@ public class FlowDebugRunnerTests
        Assert.Contains("Nope", ex.Message);
    }

+    /// <summary>Verifies that running a script on an out-of-scope site is refused before flattening.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunScript_OutOfScopeSite_IsRefused_BeforeFlattening()
    {
@@ -923,6 +1003,8 @@ public class FlowDebugRunnerTests
        await pipeline.DidNotReceiveWithAnyArgs().FlattenAndValidateAsync(default, default, default, default);
    }

+    /// <summary>Verifies that an unserializable return value in a call-kind script run still writes the root row.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunScript_CallKind_UnserializableReturnValue_StillWritesTheRootRow()
    {
@@ -945,6 +1027,8 @@ public class FlowDebugRunnerTests
        Assert.Equal(AuditKind.RouteCall, written.AsRow().Kind);
    }

+    /// <summary>Verifies that a transport fault in a call-kind script run still writes the root row as call failed.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunScript_CallKind_TransportFault_StillWritesTheRootRow_AsCallFailed()
    {
@@ -968,6 +1052,8 @@ public class FlowDebugRunnerTests
        Assert.Equal(AuditKind.RouteCall, written.AsRow().Kind);
    }

+    /// <summary>Verifies that an ask timeout in a call-kind script run reports the timeout code.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunScript_CallKind_AskTimeout_ReportsTimeoutCode()
    {
@@ -995,6 +1081,8 @@ public class FlowDebugRunnerTests
        throw new InvalidOperationException("unreachable");
    }

+    /// <summary>Verifies that a timeout in a call-kind script run reports the timeout code.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunScript_CallKind_Timeout_ReportsTimeoutCode()
    {
@@ -1018,6 +1106,8 @@ public class FlowDebugRunnerTests
        Assert.Equal(AuditStatus.Failed, written.AsRow().Status);
    }

+    /// <summary>Verifies that the root row of a call-kind script run is redacted when a redactor is registered.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task RunScript_CallKind_RootRow_IsRedacted_WhenARedactorIsRegistered()
    {
@@ -1038,6 +1128,9 @@ public class FlowDebugRunnerTests
    /// <summary>Upper-cases <c>DetailsJson</c> so a test can see the filtered copy land.</summary>
    private sealed class UpperRedactor : IAuditRedactor
    {
+        /// <summary>Returns a copy of the event with its details upper-cased.</summary>
+        /// <param name="rawEvent">The event to filter.</param>
+        /// <returns>The filtered event.</returns>
        public AuditEvent Apply(AuditEvent rawEvent)
            => rawEvent with { DetailsJson = rawEvent.DetailsJson?.ToUpperInvariant() };
    }