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
@@ -47,6 +47,7 @@ public class ReconcileStartsInstanceTests : TestKit, IDisposable
    private readonly SharedScriptLibrary _sharedScriptLibrary;
    private readonly TestLocalDb _localDb;

+    /// <summary>Initializes the test class with a fresh local database and the actor-system fixtures.</summary>
    public ReconcileStartsInstanceTests()
    {
        _localDb = TestLocalDb.CreateTemp("reconcile-start-test");
@@ -59,6 +60,7 @@ public class ReconcileStartsInstanceTests : TestKit, IDisposable
            _compilationService, NullLogger<SharedScriptLibrary>.Instance);
    }

+    /// <inheritdoc />
    void IDisposable.Dispose()
    {
        // Shut the actors down BEFORE the ILocalDb they write through is disposed.
@@ -79,13 +81,13 @@ public class ReconcileStartsInstanceTests : TestKit, IDisposable
    /// would still pass, while proving the BOOT LOAD works rather than the startup-reconcile path
    /// it claims to cover. A sleep only makes that race unlikely; on a loaded machine the load can
    /// still be in flight when it expires, and the test silently changes what it proves instead of
-    /// failing. The row-78 fix session hit exactly this trap and closed it in
-    /// <c>InstanceSweepSelfHealTests</c>; this is the same gate, applied to row 67's suite.
+    /// failing. An earlier fix session hit exactly this trap and closed it in
+    /// <c>InstanceSweepSelfHealTests</c>; this is the same gate, applied to this suite.
    /// </para>
    ///
    /// <para>
    /// The sweep is disabled (<c>InstanceSweepIntervalSeconds = 0</c>) so these tests keep proving
-    /// the row-67 <see cref="EnsureInstanceStartedCommand"/> path specifically — with the sweep
+    /// the <see cref="EnsureInstanceStartedCommand"/> path specifically — with the sweep
    /// armed, its periodic self-heal would independently start the same instances and the suite
    /// would no longer distinguish the two mechanisms.
    /// </para>
@@ -165,7 +167,7 @@ public class ReconcileStartsInstanceTests : TestKit, IDisposable
    // ── The reproduction ──

    /// <summary>
-    /// THE row-67 reproduction, end to end over one shared storage file: the node boots with no
+    /// THE reproduction, end to end over one shared storage file: the node boots with no
    /// config for an enabled instance (so the Deployment Manager's startup load starts nothing),
    /// then the startup reconcile pass fetches and stores that config. The instance must be
    /// RUNNING afterwards — not merely present in SQLite waiting for a second restart.
@@ -176,6 +178,7 @@ public class ReconcileStartsInstanceTests : TestKit, IDisposable
    /// Instance Actor.
    /// </para>
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task StartupReconcile_StoringConfigForEnabledInstance_StartsTheInstanceActor()
    {
@@ -221,6 +224,7 @@ public class ReconcileStartsInstanceTests : TestKit, IDisposable
    /// <c>deployment</c> site event naming the instance, so an operator can see that a node
    /// booted without a config and self-repaired.
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task ReconcileStartedInstance_EmitsASiteEvent()
    {
@@ -319,6 +323,7 @@ public class ReconcileStartsInstanceTests : TestKit, IDisposable
    /// The command is idempotent: both site nodes' reconcile actors legitimately raise it for
    /// the same instance, and a repeat must not disturb (or replace) the running actor.
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task EnsureInstanceStarted_IsIdempotent_WhenAlreadyRunning()
    {
@@ -353,6 +358,7 @@ public class ReconcileStartsInstanceTests : TestKit, IDisposable
    /// stopped even if an ensure-started request arrives for it (e.g. a disable landed between
    /// the reconcile fetch and the start request).
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task EnsureInstanceStarted_DisabledInstance_StaysStopped()
    {
@@ -373,6 +379,7 @@ public class ReconcileStartsInstanceTests : TestKit, IDisposable
    /// no-op — the normal case on an unreplicated site whose peer node healed its own file.
    /// The Deployment Manager must not crash or invent an instance.
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task EnsureInstanceStarted_UnknownInstance_IsAQuietNoOp()
    {
@@ -404,11 +411,12 @@ public class ReconcileStartsInstanceTests : TestKit, IDisposable
    ///
    /// <para>
    /// This test holds the read open, commits a disable behind it, then releases it — the
-    /// interleaving the fix's store-write-generation stamp exists to reject (arch-review
-    /// 2026-08-19 P1-1). <b>Fails before the fix</b>: the stale enabled snapshot passes every
+    /// interleaving the fix's store-write-generation stamp exists to reject.
+    /// <b>Fails before the fix</b>: the stale enabled snapshot passes every
    /// guard and the Instance Actor is created for a disabled instance.
    /// </para>
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task EnsureInstanceStarted_ResultLandingAfterADisable_IsDiscarded()
    {
@@ -451,6 +459,7 @@ public class ReconcileStartsInstanceTests : TestKit, IDisposable
    ///
    /// <para><b>Fails before the fix</b> at the final assert.</para>
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task EnsureInstanceStarted_ResultLandingAfterADelete_IsDiscarded()
    {
@@ -485,8 +494,9 @@ public class ReconcileStartsInstanceTests : TestKit, IDisposable
    /// <summary>
    /// The complement of the two tests above: with no mutation in the read's window the heal
    /// still starts the instance, so the generation check rejects superseded snapshots without
-    /// disabling the row-67 repair itself.
+    /// disabling the repair itself.
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task EnsureInstanceStarted_ResultLandingWithNoInterveningWrite_StillStarts()
    {
@@ -523,7 +533,7 @@ public class ReconcileStartsInstanceTests : TestKit, IDisposable
    /// Reads real storage every time and only parks AFTER the read, so the returned snapshot is
    /// exactly what production would have seen at that instant. Inert until <see cref="Arm"/>
    /// is called, which keeps the Deployment Manager's boot load — a separate seam
-    /// (<c>_configLoader</c>, register P1-4) untouched by this gate — unblocked.
+    /// (<c>_configLoader</c>) untouched by this gate — unblocked.
    /// </para>
    /// </summary>
    private sealed class GatedConfigLoader(SiteStorageService storage)
@@ -532,13 +542,20 @@ public class ReconcileStartsInstanceTests : TestKit, IDisposable
        private readonly TaskCompletionSource _parked =
            new(TaskCreationOptions.RunContinuationsAsynchronously);

+        /// <summary>Arms the gate so the next load parks until released.</summary>
        public void Arm() => _release = new TaskCompletionSource(
            TaskCreationOptions.RunContinuationsAsynchronously);

+        /// <summary>Releases the parked load so it can complete.</summary>
        public void Release() => _release!.TrySetResult();

+        /// <summary>Waits until a load has parked at the gate.</summary>
+        /// <returns>A task that completes once a load is parked at the gate.</returns>
        public Task WaitUntilParkedAsync() => _parked.Task.WaitAsync(TimeSpan.FromSeconds(10));

+        /// <summary>Reads the deployed config from storage and then parks at the gate if armed.</summary>
+        /// <param name="instanceName">The unique name of the instance to load.</param>
+        /// <returns>The stored deployed instance, or null when none exists.</returns>
        public async Task<DeployedInstance?> LoadAsync(string instanceName)
        {
            var config = await storage.GetDeployedConfigAsync(instanceName);
@@ -559,10 +576,14 @@ public class ReconcileStartsInstanceTests : TestKit, IDisposable
    private sealed class FakeConfigFetcher : IDeploymentConfigFetcher
    {
        private readonly Func<string, Task<string>> _behavior;
+        /// <summary>Gets the recorded fetch calls (base URL, deployment id, token).</summary>
        public ConcurrentQueue<(string BaseUrl, string DeploymentId, string Token)> Calls { get; } = new();

+        /// <summary>Initializes the fake with the per-deployment-id behavior to run on each fetch.</summary>
+        /// <param name="behavior">Maps a deployment id to the fetch result.</param>
        public FakeConfigFetcher(Func<string, Task<string>> behavior) => _behavior = behavior;

+        /// <inheritdoc />
        public async Task<string> FetchAsync(
            string centralFetchBaseUrl, string deploymentId, string token, CancellationToken ct)
        {