docs: strip task-tracking IDs from code comments and fill missing XML docs
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m16s
ci / java (push) Successful in 2m5s
ci / portable (push) Failing after 5m9s

Tracking IDs are review bookkeeping that rots in shipped source; the rationale they tagged is kept. Comment-only change (CommentChecker 458 -> 16 false positives).
This commit is contained in:
Joseph Doherty
2026-10-07 15:34:32 -04:00
parent f2e0861709
commit f40409a688
115 changed files with 549 additions and 411 deletions
@@ -8,7 +8,7 @@ using ZB.MOM.WW.MxGateway.Server.Configuration;
namespace ZB.MOM.WW.MxGateway.Tests.Configuration;
/// <summary>
/// Gateway-owned validation of the shared <see cref="GalaxyRepositoryOptions"/> (SEC-33): the Galaxy
/// Gateway-owned validation of the shared <see cref="GalaxyRepositoryOptions"/>: the Galaxy
/// package binds the options but ships no validator, so the gateway rejects a persisted snapshot
/// whose path is blank, invalid, or non-rooted on the running host, and supplies a rooted per-OS
/// default when the shipped config leaves the path blank.
@@ -109,7 +109,7 @@ public sealed class GalaxyRepositoryOptionsValidatorTests
/// <summary>
/// Verifies the gateway supplies a rooted per-OS default when the shipped config leaves
/// SnapshotCachePath blank, so the removed appsettings literal is not needed and validation
/// passes on any host (SEC-33). Resolving the options triggers the registered validator.
/// passes on any host. Resolving the options triggers the registered validator.
/// </summary>
[Fact]
public void Build_DefaultsBlankSnapshotCachePathToRootedDefault()
@@ -9,7 +9,7 @@ namespace ZB.MOM.WW.MxGateway.Tests.Configuration;
/// </summary>
/// <remarks>
/// The projection is hand-written member by member, so an option that exists and validates can
/// still be invisible on the settings page — which is exactly what happened to the two SEC-25
/// still be invisible on the settings page — which is exactly what happened to the two
/// dashboard-ACL options. These tests pin the dashboard-tag members to the options they come
/// from; the redaction assertions pin the opposite invariant, that the two secret-bearing members
/// are the only ones masked.
@@ -86,7 +86,7 @@ public sealed class GatewayOptionsTests
["MxGateway:Events:QueueCapacity"] = "256",
["MxGateway:Dashboard:Enabled"] = "false",
["MxGateway:Protocol:MaxGrpcMessageBytes"] = "8388608",
// The frame-headroom rule is two-sided (IPC-33): the worker-frame maximum must sit
// The frame-headroom rule is two-sided: the worker-frame maximum must sit
// between one and two 64 KiB envelope reserves above the gRPC cap, so moving the
// gRPC cap without moving this one no longer validates. Kept at one reserve above,
// the same shape as the shipped default.
@@ -175,7 +175,7 @@ public sealed class GatewayOptionsTests
/// but only the binder decides whether that instance is populated in place or replaced by a
/// default-comparer one. Asserting the comparer on a hand-constructed <see cref="DashboardOptions"/>
/// would prove nothing about the configured path; a mis-cased LDAP group name from the directory
/// would then silently grant no tags, and the SEC-25 ACL would deny with no diagnostic.
/// would then silently grant no tags, and the dashboard session ACL would deny with no diagnostic.
/// </remarks>
[Fact]
public void DashboardOptions_GroupToTag_BindsCaseInsensitively()
@@ -778,7 +778,7 @@ public sealed class GatewayOptionsValidatorTests
}
/// <summary>
/// Verifies rooting is host-meaningful (SEC-33): a Windows drive-qualified literal fails on a
/// Verifies rooting is host-meaningful: a Windows drive-qualified literal fails on a
/// Unix host (where it is not rooted) rather than being blessed and written as a junk-named
/// relative file. On Windows the same literal is genuinely rooted and passes.
/// </summary>
@@ -805,7 +805,7 @@ public sealed class GatewayOptionsValidatorTests
}
/// <summary>
/// Verifies MxGateway:Events:QueueCapacity above int.MaxValue/2 fails (GWC-24 rider): the value
/// Verifies MxGateway:Events:QueueCapacity above int.MaxValue/2 fails: the value
/// flows into WorkerClient as checked(2 * EventChannelCapacity), which would otherwise overflow.
/// </summary>
[Fact]
@@ -1078,7 +1078,7 @@ public sealed class GatewayOptionsValidatorTests
result.Failures!,
f => f.Contains("MxGateway:Ldap:ServiceAccountPassword is required when LDAP login is enabled."));
// SEC-36: the message must steer the operator to the two supported out-of-band channels
// The message must steer the operator to the two supported out-of-band channels
// (dev user-secrets, deployed env var) so a blanked/unresolved credential never gets
// "fixed" by re-committing a value.
Assert.Contains("dotnet user-secrets set", failure);
@@ -1258,7 +1258,7 @@ public sealed class GatewayOptionsValidatorTests
}
/// <summary>
/// Verifies the headroom rule's upper half (IPC-33): a worker-frame maximum more than two
/// Verifies the headroom rule's upper half: a worker-frame maximum more than two
/// envelope reserves above the gRPC cap is rejected. The worker budgets a DrainEvents reply at
/// the frame maximum less two reserves and the gateway returns that same reply through
/// <c>Invoke</c>, so a wider gap lets the worker pack a reply the pipe carries and the gRPC send
@@ -18,6 +18,10 @@ namespace ZB.MOM.WW.MxGateway.Tests.Configuration;
/// </summary>
public sealed class PreHostSecretExpansionTests
{
/// <summary>
/// A seeded secret reference in configuration resolves to its plaintext.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ExpandConfiguration_SeededReference_ResolvesToPlaintext()
{
@@ -37,6 +41,7 @@ public sealed class PreHostSecretExpansionTests
/// <c>${secret:ldap/mxgateway/bind}</c>. Proves that exact reference at that exact key resolves to
/// the seeded plaintext through the same pre-host expander the host runs.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ExpandConfiguration_LdapBindReference_ResolvesToSeededPassword()
{
@@ -52,6 +57,10 @@ public sealed class PreHostSecretExpansionTests
Assert.Equal(bindPassword, config["MxGateway:Ldap:ServiceAccountPassword"]);
}
/// <summary>
/// A reference to an absent secret throws instead of leaving the token in place.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ExpandConfiguration_MissingReference_ThrowsFailClosed()
{
@@ -81,8 +90,11 @@ public sealed class PreHostSecretExpansionTests
_envVarName = envVarName;
}
/// <summary>Gets the secret resolver from the fixture's DI graph.</summary>
public ISecretResolver Resolver => _provider.GetRequiredService<ISecretResolver>();
/// <summary>Creates a fixture with a unique SQLite store and master-key environment variable.</summary>
/// <returns>The migrated fixture.</returns>
public static SecretsFixture Create()
{
string unique = Guid.NewGuid().ToString("N");
@@ -111,8 +123,13 @@ public sealed class PreHostSecretExpansionTests
return new SecretsFixture(provider, sqlitePath, envVarName);
}
// Seals a plaintext value under a fresh DEK and upserts it — the same store/cipher pair the
// CLI 'secret set' verb uses.
/// <summary>
/// Seals a plaintext value under a fresh DEK and upserts it, using the same store/cipher pair
/// the CLI 'secret set' verb uses.
/// </summary>
/// <param name="name">The secret name.</param>
/// <param name="plaintext">The plaintext value to store.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public async Task SeedAsync(string name, string plaintext)
{
var secretName = new SecretName(name);
@@ -122,11 +139,15 @@ public sealed class PreHostSecretExpansionTests
await store.UpsertAsync(sealed_, default);
}
/// <summary>Builds an in-memory configuration from the given key/value pairs.</summary>
/// <param name="entries">The configuration entries.</param>
/// <returns>The built configuration root.</returns>
public IConfigurationRoot BuildConfig(params (string Key, string Value)[] entries) =>
new ConfigurationBuilder()
.AddInMemoryCollection(entries.ToDictionary(e => e.Key, e => (string?)e.Value))
.Build();
/// <summary>Disposes the service provider and clears the test environment variable.</summary>
public void Dispose()
{
_provider.Dispose();