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
@@ -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