docs(src): fix CommentChecker findings across src/ — 1,032 → 5 (all false positives)

Comment/XML-doc changes only, no code logic:
- strip project-tracking references (WP*, P*-*, row-NN, #NN, Task N) from
  comments, keeping the explanatory rationale
- add missing summaries, <param>, <returns>, <typeparam> and <inheritdoc/>
- replace misused <inheritdoc/> with real docs; where <inheritdoc/> was
  combined with useful remarks, move the rationale into // comments
- drop stale replicationActor <param> on DeploymentManagerActor ctor

Remaining 5 are false positives (CWE-1236 x2, failures-1, year-0001, M365).
Build 0 errors / 0 warnings.
This commit is contained in:
Joseph Doherty
2026-10-07 14:12:25 -04:00
parent 3a217b9484
commit 0ffd4bdbea
217 changed files with 1224 additions and 695 deletions
@@ -27,7 +27,7 @@ public static class StartupValidator
var seedNodes = configuration.GetSection("ScadaBridge:Cluster:SeedNodes").Get<List<string>>();
// Secrets replication (the gRPC hub, and the SQL-Server ReplicatingSecretStore mode that
// preceded it) is retired in ScadaBridge (Task 11) — sites receive secrets exclusively via
// preceded it) is retired in ScadaBridge — sites receive secrets exclusively via
// Deploy Artifacts, and a replicated site store would publish DeployedSecretsMirror's local
// deletes fleet-wide. Checked unconditionally (both roles): a Site used to be the gRPC
// hub's follower half, so the flag was never Central-only.
@@ -56,7 +56,7 @@ public static class StartupValidator
.Require("ScadaBridge:Node:RemotingPort",
_ => portValid,
"must be 1-65535")
// Retired for BOTH roles (Task 11) — a Site could set this too, as the gRPC hub's
// Retired for BOTH roles — a Site could set this too, as the gRPC hub's
// follower half. Deliberately NOT folded into a role-scoped block below.
.Require("Secrets:Replication:Enabled",
_ => !secretsReplicationEnabled,
@@ -192,8 +192,8 @@ public static class StartupValidator
+ "endpoint under ScadaBridge:Communication:CentralGrpcEndpoints "
+ "(e.g. http://scadabridge-central-a:8083). Central nodes leave it empty.");
// The site hot-path audit writer's SQLite file (arch-review remediation
// WP1.2). SqliteAuditWriterOptions.DatabasePath has no default (mirrors
// The site hot-path audit writer's SQLite file (arch-review remediation).
// SqliteAuditWriterOptions.DatabasePath has no default (mirrors
// LocalDb:Path) — an unset value would previously fall back to a bare
// "auditlog.db" resolved relative to the process CWD, which on the docker
// rig is the container's ephemeral overlayfs, not the mounted /app/data
@@ -245,6 +245,8 @@ public static class StartupValidator
}
/// <summary>Non-fatal configuration findings. Collected separately from <see cref="Validate"/> because this runs before the logger exists; Program.cs logs each entry at Warning once Serilog is configured.</summary>
/// <param name="configuration">The application configuration to inspect.</param>
/// <returns>The warning messages to log; empty when there are none.</returns>
public static IReadOnlyList<string> CollectWarnings(IConfiguration configuration)
{
var role = configuration.GetSection("ScadaBridge:Node")["Role"];
@@ -270,7 +272,7 @@ public static class StartupValidator
// both central nodes to deploy the SAME secret set; a per-node store means each node has
// silently drifted the moment anyone edits a secret on only one of them.
//
// No Secrets:Replication:Enabled gate here any more (Task 11): that flag is now a hard
// No Secrets:Replication:Enabled gate here any more: that flag is now a hard
// Validate() failure on either role (the gRPC hub and SQL-Server secrets replication are
// both retired), so CollectWarnings never runs with it true on a config that also passed
// Validate — the old gate that suppressed this warning when replication was on is dead code
@@ -284,8 +286,8 @@ public static class StartupValidator
+ "deploy its own secret set to sites; set Secrets:Store:Provider=SqlServer");
}
// Review round 1, Minor #4: a config that still carries Secrets:Replication or
// Secrets:GrpcHub child keys — left over from before Task 11 retired the hub — is not
// A config that still carries Secrets:Replication or
// Secrets:GrpcHub child keys — left over from before the hub was retired — is not
// itself an error (Validate already rejects Enabled=true outright), but every key under
// either section is now silently ignored. That is worth a Warning so an operator cleans
// QA/prod appsettings rather than assuming a still-present Mode/BearerToken/Endpoint value
@@ -307,7 +309,7 @@ public static class StartupValidator
/// <summary>
/// Whether <c>Secrets:Replication:Enabled</c> is "set" — read as a raw string rather than
/// <c>IConfiguration.GetValue&lt;bool&gt;</c> (review round 1, Minor #3), which throws a raw
/// <c>IConfiguration.GetValue&lt;bool&gt;</c> which throws a raw
/// binder <see cref="InvalidOperationException"/> on a non-boolean value like <c>"yes"</c> or
/// <c>"1"</c>, so a malformed leftover key would surface as an unrelated parse crash instead of
/// the designed retirement message in <see cref="Validate"/>. Any value other than absent,