docs(comments): strip internal task/milestone/bundle bookkeeping from code comments

Remove project bookkeeping citations from shipped code comments across the
solution: hyphenated task IDs (WP-14, StoreAndForward-025), milestone/task/
issue refs (M3, Task 4, Audit Log #23, #21), Bundle X task-bundle labels,
and C/D/K/S/T phase labels.

Comment text only — no code logic, string/log literals, or XML-doc structure
changed. Genuine descriptions are preserved (only the citation is stripped),
and technical lookalikes are retained (UTF-8, SHA-256, T00:00:00, M365,
UTC-5, pre-C4/pre-C5 schema versions). Flagged by the new CommentChecker
TaskReferenceInComment / TrackingReferenceInComment checks plus targeted
grep passes; full solution builds clean, append-only guard tests pass.
This commit is contained in:
Joseph Doherty
2026-07-07 11:03:26 -04:00
parent 67005ca4c0
commit 9cff87fe85
435 changed files with 2338 additions and 2547 deletions
@@ -1,7 +1,7 @@
namespace ZB.MOM.WW.ScadaBridge.NotificationService;
/// <summary>
/// NS-009: Scrubs SMTP credential secrets out of free text (typically exception
/// Scrubs SMTP credential secrets out of free text (typically exception
/// messages echoed back by an SMTP server) before that text is written to a log.
/// MailKit authentication exceptions can contain server responses that quote the
/// supplied credentials; this prevents a password, client secret, or OAuth2 token
@@ -25,7 +25,7 @@ public static class CredentialRedactor
/// <c>tenantId:clientId:clientSecret</c>. May be null.
/// </param>
/// <summary>
/// NS-025: minimum length for a colon-separated SECRET component to be
/// Minimum length for a colon-separated SECRET component to be
/// considered worth masking. Twelve characters is the standard heuristic
/// for "long enough to be a password / client secret"; shorter components
/// (e.g. a 4-char user name like <c>root</c>, or a 7-char "from" alias)
@@ -52,7 +52,7 @@ public static class CredentialRedactor
var result = text;
// NS-025: redact only the obviously-secret slots — the LAST
// Redact only the obviously-secret slots — the LAST
// colon-separated component (the password in Basic, the client
// secret in OAuth2) and the whole packed string — not the user
// name / tenant id / client id. A short user name like "root" or
@@ -4,7 +4,7 @@ using ZB.MOM.WW.ScadaBridge.Commons.Entities.Notifications;
namespace ZB.MOM.WW.ScadaBridge.NotificationService;
/// <summary>
/// NS-008: Validates the sender and recipient email addresses before an SMTP
/// Validates the sender and recipient email addresses before an SMTP
/// delivery is attempted, so a malformed address surfaces as a clean error
/// string rather than a <c>ParseException</c> escaping the delivery path.
/// <para>
@@ -9,12 +9,12 @@ public interface ISmtpClientWrapper
/// Connects to the SMTP server.
/// </summary>
/// <param name="tlsMode">
/// NS-005: explicit three-state TLS mode (None/StartTls/Ssl) — replaces the old
/// Explicit three-state TLS mode (None/StartTls/Ssl) — replaces the old
/// <c>bool useTls</c> which could not represent implicit-SSL and silently fell
/// back to opportunistic negotiation for non-StartTLS configurations.
/// </param>
/// <param name="connectionTimeoutSeconds">
/// NS-007: SMTP connection/operation timeout in seconds. A non-positive value
/// SMTP connection/operation timeout in seconds. A non-positive value
/// leaves the client's default timeout in place.
/// </param>
/// <param name="host">SMTP server hostname or IP address.</param>
@@ -31,9 +31,9 @@ public interface ISmtpClientWrapper
/// <param name="authType">Authentication mechanism (e.g. <c>PLAIN</c>, <c>XOAUTH2</c>).</param>
/// <param name="credentials">Credential string appropriate for the auth type, or null.</param>
/// <param name="oauth2UserName">
/// NS-021: mailbox identity the OAuth2 access token was issued for (typically
/// Mailbox identity the OAuth2 access token was issued for (typically
/// the SMTP <c>FromAddress</c>). Used as the <c>user=</c> field of the XOAUTH2
/// SASL initial response — M365 rejects an empty/mismatched user with
/// SASL initial response — Microsoft 365 rejects an empty/mismatched user with
/// <c>535 5.7.3</c>. Ignored for non-OAuth2 auth types; default <c>null</c> for
/// callers that do not authenticate with OAuth2.
/// </param>
@@ -5,13 +5,13 @@ using MimeKit;
namespace ZB.MOM.WW.ScadaBridge.NotificationService;
/// <summary>
/// WP-11: MailKit-based SMTP client wrapper.
/// MailKit-based SMTP client wrapper.
/// Supports OAuth2 Client Credentials (M365) and Basic Auth.
/// BCC delivery, plain text.
/// </summary>
/// <remarks>
/// <para>
/// <b>Lifetime — one wrapper, one delivery (NS-022).</b>
/// <b>Lifetime — one wrapper, one delivery.</b>
/// This wrapper owns a SINGLE underlying <see cref="MailKit.Net.Smtp.SmtpClient"/>
/// — it is NOT a connection pool. MailKit's <c>SmtpClient</c> is a single TCP/TLS
/// connection holder and is NOT thread-safe; reusing one across concurrent or
@@ -31,14 +31,14 @@ namespace ZB.MOM.WW.ScadaBridge.NotificationService;
/// </para>
/// <para>
/// Do not reuse one wrapper across deliveries. <see cref="ConnectAsync"/>
/// mutates <c>_client.Timeout</c> per call (NS-007), and the underlying
/// mutates <c>_client.Timeout</c> per call, and the underlying
/// <c>SmtpClient</c> rejects concurrent send calls — both are latent footguns
/// for any caller tempted to "fix" the factory into a true singleton.
/// </para>
/// </remarks>
public class MailKitSmtpClientWrapper : ISmtpClientWrapper, IDisposable
{
// NS-022: ONE SmtpClient per wrapper — see class-level remarks. This is NOT a
// ONE SmtpClient per wrapper — see class-level remarks. This is NOT a
// connection pool. MailKit's SmtpClient holds a single TCP/TLS connection and
// is not thread-safe; the wrapper is meant for a single connect/auth/send/
// disconnect cycle per instance, after which it MUST be disposed.
@@ -52,7 +52,7 @@ public class MailKitSmtpClientWrapper : ISmtpClientWrapper, IDisposable
int connectionTimeoutSeconds,
CancellationToken cancellationToken = default)
{
// NS-005: map the explicit three-state TLS mode onto MailKit's socket
// Map the explicit three-state TLS mode onto MailKit's socket
// options. The old code collapsed everything to a boolean and used
// SecureSocketOptions.Auto for the non-StartTLS case, which let MailKit
// opportunistically negotiate TLS even when "None" was configured and
@@ -65,7 +65,7 @@ public class MailKitSmtpClientWrapper : ISmtpClientWrapper, IDisposable
_ => throw new ArgumentOutOfRangeException(nameof(tlsMode), tlsMode, "Unknown TLS mode."),
};
// NS-007: honour the configured connection timeout. SmtpClient.Timeout is
// Honour the configured connection timeout. SmtpClient.Timeout is
// in milliseconds and applies to connect/auth/send operations.
if (connectionTimeoutSeconds > 0)
{
@@ -82,7 +82,7 @@ public class MailKitSmtpClientWrapper : ISmtpClientWrapper, IDisposable
string? oauth2UserName = null,
CancellationToken cancellationToken = default)
{
// NS-016: missing/unparseable credentials and an unrecognised auth type used
// Missing/unparseable credentials and an unrecognised auth type used
// to make this method silently return and the connection then sent mail
// unauthenticated — masking a misconfiguration against an open relay and, at
// worst, sending where authentication was required. Authentication being
@@ -109,7 +109,7 @@ public class MailKitSmtpClientWrapper : ISmtpClientWrapper, IDisposable
break;
case "oauth2":
// NS-021: the XOAUTH2 SASL initial response embeds a `user=<userName>`
// The XOAUTH2 SASL initial response embeds a `user=<userName>`
// field that M365 (and most OAuth2-enabled SMTP relays) require to
// match the mailbox identity the token was issued for. An empty user
// gets rejected with `535 5.7.3`. The token (credentials) is
@@ -5,7 +5,7 @@ namespace ZB.MOM.WW.ScadaBridge.NotificationService;
/// <c>ScadaBridge:Notification</c> configuration section.
///
/// SMTP settings are primarily carried by the deployed <c>SmtpConfiguration</c>
/// entity. NS-017: these values are the fallback used by the central
/// entity. These values are the fallback used by the central
/// Notification Outbox's <c>EmailNotificationDeliveryAdapter</c> when the
/// corresponding <c>SmtpConfiguration</c> field is left unset (non-positive) on a
/// partially deployed row — a value present on the row always takes precedence.
@@ -7,9 +7,9 @@ using Microsoft.Extensions.Logging;
namespace ZB.MOM.WW.ScadaBridge.NotificationService;
/// <summary>
/// WP-11: OAuth2 Client Credentials token lifecycle — fetch, cache, refresh on expiry.
/// OAuth2 Client Credentials token lifecycle — fetch, cache, refresh on expiry.
/// Used for Microsoft 365 SMTP authentication.
/// NS-006: tokens are cached per credential identity (tenant/client/secret), so a
/// Tokens are cached per credential identity (tenant/client/secret), so a
/// second SMTP configuration with different credentials never receives the first
/// configuration's token.
/// </summary>
@@ -18,7 +18,7 @@ public class OAuth2TokenService
private readonly IHttpClientFactory _httpClientFactory;
private readonly ILogger<OAuth2TokenService> _logger;
// NS-006: cache keyed by a hash of the credential string. Each distinct
// Cache keyed by a hash of the credential string. Each distinct
// tenant/client/secret triple gets its own cached token and its own lock.
private readonly ConcurrentDictionary<string, CacheEntry> _cache = new();
@@ -93,7 +93,7 @@ public class OAuth2TokenService
entry.Token = token;
entry.Expiry = DateTimeOffset.UtcNow.AddSeconds(expiresIn - 60); // Refresh 60s before expiry
// NS-009: the token endpoint identity is logged by tenant only — never
// The token endpoint identity is logged by tenant only — never
// the client secret or the access token itself.
_logger.LogInformation(
"OAuth2 token refreshed for tenant {Tenant}, expires in {ExpiresIn}s", tenantId, expiresIn);
@@ -106,7 +106,7 @@ public class OAuth2TokenService
}
/// <summary>
/// NS-006: a stable, non-reversible key for the credential string so the cache
/// A stable, non-reversible key for the credential string so the cache
/// is partitioned by credential identity without holding the secret as a key.
/// </summary>
private static string CredentialKey(string credentials)
@@ -11,7 +11,7 @@ public static class ServiceCollectionExtensions
/// Central-only — sites no longer deliver notifications (see
/// <c>Component-NotificationService.md</c>), and the orphaned site-shaped
/// <c>NotificationDeliveryService</c> + <c>INotificationDeliveryService</c> contract
/// was removed (NS-019). Notification dispatch lives in <c>ZB.MOM.WW.ScadaBridge.NotificationOutbox</c>.
/// was removed. Notification dispatch lives in <c>ZB.MOM.WW.ScadaBridge.NotificationOutbox</c>.
/// </summary>
/// <param name="services">The service collection to register into.</param>
/// <returns>The same <paramref name="services"/> collection, for chaining.</returns>
@@ -5,7 +5,7 @@ using MailKit.Net.Smtp;
namespace ZB.MOM.WW.ScadaBridge.NotificationService;
/// <summary>
/// NS-002/NS-003: The classification of an SMTP delivery failure. This decides
/// The classification of an SMTP delivery failure. This decides
/// whether a failure is retried or surfaced to the caller, so it is part of the
/// system's correctness-relevant behaviour.
/// </summary>
@@ -22,12 +22,12 @@ public enum SmtpErrorClass
}
/// <summary>
/// NS-002/NS-003: Classifies an SMTP failure using MailKit's typed exceptions and
/// Classifies an SMTP failure using MailKit's typed exceptions and
/// the numeric <see cref="SmtpStatusCode"/> rather than locale-dependent substring
/// matching on the exception message.
/// <para>
/// Public and shared: the central Notification Outbox's <c>EmailNotificationDeliveryAdapter</c>
/// routes every SMTP failure through this single policy. (NS-019: the orphaned site-side
/// routes every SMTP failure through this single policy. (The orphaned site-side
/// <c>NotificationDeliveryService</c> that previously co-used this classifier was removed
/// when sites stopped delivering notifications.)
/// </para>
@@ -1,7 +1,7 @@
namespace ZB.MOM.WW.ScadaBridge.NotificationService;
/// <summary>
/// NS-005: The three TLS modes the design doc defines for SMTP connections.
/// The three TLS modes the design doc defines for SMTP connections.
/// A single boolean cannot represent the requirement, so the configured
/// <c>SmtpConfiguration.TlsMode</c> string is parsed into this three-state enum.
/// </summary>
@@ -18,7 +18,7 @@ public enum SmtpTlsMode
}
/// <summary>
/// NS-005: Parses the free-text <c>SmtpConfiguration.TlsMode</c> value into a
/// Parses the free-text <c>SmtpConfiguration.TlsMode</c> value into a
/// <see cref="SmtpTlsMode"/>, rejecting unknown values rather than silently
/// falling back to opportunistic negotiation.
/// </summary>