dohertj2/ScadaBridge
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files
src/ZB.MOM.WW.ScadaBridge.SiteEventLogging/EventLogPurgeService.cs
+3 -3
View File
@@ -5,7 +5,7 @@ using Microsoft.Extensions.Options;
namespace ZB.MOM.WW.ScadaBridge.SiteEventLogging;
/// <summary>
/// SiteEventLogging-019: predicate the <see cref="EventLogPurgeService"/>
/// Predicate the <see cref="EventLogPurgeService"/>
/// consults at the top of every purge tick to decide whether THIS node should
/// run the daily purge. The design states "a daily background job runs on the
/// active node and deletes all events older than 30 days"; the standby's local
@@ -40,7 +40,7 @@ public class EventLogPurgeService : BackgroundService
/// <param name="options">Site event log options (retention days, storage cap, purge interval).</param>
/// <param name="logger">Logger instance.</param>
/// <param name="isActiveNode">
/// SiteEventLogging-019: optional active-node check. When <c>null</c>, the
/// Optional active-node check. When <c>null</c>, the
/// service runs the purge on every tick (preserves the pre-fix behaviour
/// for non-clustered hosts and existing tests). When supplied — e.g. by
/// the Host on a site node — each tick early-exits on the standby so the
@@ -84,7 +84,7 @@ public class EventLogPurgeService : BackgroundService
{
try
{
// SiteEventLogging-019: gate every tick on the active-node check.
// Gate every tick on the active-node check.
// The standby's local SQLite receives no writes, so purging there
// is harmless but unnecessary; the design (Component-SiteEventLogging
// → Storage) explicitly states the purge runs on the active node.
src/ZB.MOM.WW.ScadaBridge.SiteEventLogging/EventLogQueryService.cs
+6 -6
View File
@@ -53,7 +53,7 @@ public class EventLogQueryService : IEventLogQueryService
{
try
{
// SiteEventLogging-017: clamp caller-supplied PageSize to a hard upper
// Clamp caller-supplied PageSize to a hard upper
// bound so a central client sending int.MaxValue can't force the query
// to materialise the entire log into a single list while holding the
// shared write lock. Silent clamp — misconfigured clients still get a
@@ -73,7 +73,7 @@ public class EventLogQueryService : IEventLogQueryService
if (request.From.HasValue)
{
// SiteEventLogging-024 (re-opens -016): timestamps are stored as ISO
// Timestamps are stored as ISO
// 8601 "o" UTC strings (always +00:00). The store compares them
// lexicographically (BINARY collation), so the bound MUST be
// normalised to UTC before ToString("o") — otherwise a non-UTC
@@ -86,7 +86,7 @@ public class EventLogQueryService : IEventLogQueryService
if (request.To.HasValue)
{
// SiteEventLogging-024: normalise the upper bound to UTC for the same
// Normalise the upper bound to UTC for the same
// reason as $from above.
whereClauses.Add("timestamp <= $to");
parameters.Add(new SqliteParameter("$to", request.To.Value.ToUniversalTime().ToString("o")));
@@ -115,7 +115,7 @@ public class EventLogQueryService : IEventLogQueryService
// Keyword search is a literal substring match. The LIKE
// metacharacters % and _ (and the escape char itself) must be
// escaped so identifiers such as "store_and_forward" or a literal
// "%" are not misinterpreted as wildcards (SiteEventLogging-013).
// "%" are not misinterpreted as wildcards.
var escaped = EscapeLikePattern(request.KeywordFilter);
whereClauses.Add(
"(message LIKE $keyword ESCAPE '\\' OR source LIKE $keyword ESCAPE '\\')");
@@ -151,8 +151,8 @@ public class EventLogQueryService : IEventLogQueryService
{
rows.Add(new EventLogEntry(
Id: reader.GetInt64(0),
// Parse with explicit invariant culture and round-trip style
// (SiteEventLogging-021). Stored values are ISO 8601 "o" UTC
// Parse with explicit invariant culture and round-trip style.
// Stored values are ISO 8601 "o" UTC
// (see SiteEventLogger.LogEventAsync), and the recorder's
// emitted offset is always +00:00; AssumeUniversal +
// AdjustToUniversal guarantees the parsed value is UTC and
src/ZB.MOM.WW.ScadaBridge.SiteEventLogging/ISiteEventLogger.cs
+2 -2
View File
@@ -30,10 +30,10 @@ public interface ISiteEventLogger
string? details = null);
/// <summary>
/// SiteEventLogging-018: total number of event writes that have failed
/// Total number of event writes that have failed
/// (SQLite error, disk full, bounded-queue overflow drop, etc.) since this
/// logger was created. Polled by <c>SiteEventLogFailureCountReporter</c>
/// (HealthMonitoring — M2.16 / #30) every 30 s and surfaced on the site
/// (Health Monitoring) every 30 s and surfaced on the site
/// health report as <c>SiteHealthReport.SiteEventLogWriteFailures</c>.
/// </summary>
long FailedWriteCount { get; }
src/ZB.MOM.WW.ScadaBridge.SiteEventLogging/ServiceCollectionExtensions.cs
+1 -1
View File
@@ -23,7 +23,7 @@ public static class ServiceCollectionExtensions
services.AddSingleton<ISiteEventLogger>(sp => sp.GetRequiredService<SiteEventLogger>());
services.AddSingleton<IEventLogQueryService, EventLogQueryService>();
// SiteEventLogging-019: the purge service still registers on every host
// The purge service still registers on every host
// node, but it consults an optional SiteEventLogActiveNodeCheck on each
// tick and early-exits on the standby. The Host registers the real
// active-node check on site nodes; tests and non-clustered hosts leave
src/ZB.MOM.WW.ScadaBridge.SiteEventLogging/SiteEventLogOptions.cs
+2 -2
View File
@@ -11,7 +11,7 @@ public class SiteEventLogOptions
/// <summary>Maximum number of rows returned per paginated query; default 500.</summary>
public int QueryPageSize { get; set; } = 500;
/// <summary>
/// SiteEventLogging-017: hard upper bound on a caller-supplied <c>PageSize</c>. A
/// Hard upper bound on a caller-supplied <c>PageSize</c>. A
/// misbehaving or hostile central client that requests <c>int.MaxValue</c> would
/// otherwise force the query to materialise the entire log into a single list while
/// holding the shared write lock. Silent clamp; default 500 matches
@@ -21,7 +21,7 @@ public class SiteEventLogOptions
/// <summary>Interval between purge runs; default 24 hours.</summary>
public TimeSpan PurgeInterval { get; set; } = TimeSpan.FromHours(24);
/// <summary>
/// SiteEventLogging-015: bound on the background write queue. Default 10 000 events.
/// Bound on the background write queue. Default 10 000 events.
/// Overflow uses <c>BoundedChannelFullMode.DropOldest</c> — callers never block; the
/// dropped event's <c>Task</c> is faulted and <c>FailedWriteCount</c> is incremented
/// so the drop is observable.
src/ZB.MOM.WW.ScadaBridge.SiteEventLogging/SiteEventLogger.cs
+10 -10
View File
@@ -23,8 +23,8 @@ namespace ZB.MOM.WW.ScadaBridge.SiteEventLogging;
/// <see cref="LogEventAsync"/> only validates its arguments and enqueues, so callers —
/// typically Akka actor threads on hot paths — never block on disk I/O or on
/// contention for the write lock. The returned <see cref="Task"/> completes once the
/// event is durably persisted and faults if the write fails. SiteEventLogging-015:
/// when a queued event is evicted to make room for a newer one, that event's Task
/// event is durably persisted and faults if the write fails. When a queued
/// event is evicted to make room for a newer one, that event's Task
/// is faulted with <see cref="InvalidOperationException"/> and
/// <see cref="FailedWriteCount"/> is incremented so the drop is observable.
/// </para>
@@ -52,7 +52,7 @@ public class SiteEventLogger : ISiteEventLogger, IDisposable
{
_logger = logger;
// SiteEventLogging-022: Cache=Shared is a cross-connection optimisation
// Cache=Shared is a cross-connection optimisation
// that lets multiple SqliteConnections share an in-process page cache.
// This logger owns exactly one SqliteConnection and serialises all
// access through _writeLock, so the mode is dormant — at best dead
@@ -66,8 +66,8 @@ public class SiteEventLogger : ISiteEventLogger, IDisposable
InitializeSchema();
// SiteEventLogging-015: bounded queue with DropOldest preserves the
// "callers never block" guarantee (SiteEventLogging-005) while putting an
// Bounded queue with DropOldest preserves the
// "callers never block" guarantee while putting an
// upper bound on memory under sustained writer slowness. Drops are
// observable — itemDropped faults the evicted Task and increments
// FailedWriteCount.
@@ -166,7 +166,7 @@ public class SiteEventLogger : ISiteEventLogger, IDisposable
}
/// <summary>
/// SiteEventLogging-020: closed set of allowed severities. Case-sensitive to
/// Closed set of allowed severities. Case-sensitive to
/// match the SQLite default <c>BINARY</c> collation used by the query filter —
/// a row stored as <c>"error"</c> would be invisible to a query filtering on
/// <c>"Error"</c>, so the contract on the way in must match the contract on
@@ -189,7 +189,7 @@ public class SiteEventLogger : ISiteEventLogger, IDisposable
ArgumentException.ThrowIfNullOrWhiteSpace(source);
ArgumentException.ThrowIfNullOrWhiteSpace(message);
// SiteEventLogging-020: reject unknown severities so the query-time filter
// Reject unknown severities so the query-time filter
// (case-sensitive BINARY collation) and the documented enum stay in sync.
if (!AllowedSeverities.Contains(severity))
{
@@ -214,7 +214,7 @@ public class SiteEventLogger : ISiteEventLogger, IDisposable
{
// The channel is unbounded, so the only way TryWrite fails is that the
// writer has been completed (logger disposed). The event cannot be
// persisted — fault the Task (SiteEventLogging-012) rather than
// persisted — fault the Task rather than
// reporting false success, so a caller that awaits a critical audit
// event can tell it was dropped.
pending.Completion.TrySetException(
@@ -256,7 +256,7 @@ public class SiteEventLogger : ISiteEventLogger, IDisposable
{
// WithConnection returns false only when the logger has been
// disposed mid-drain; the event was not persisted. Fault the
// Task (SiteEventLogging-012) instead of reporting false
// Task instead of reporting false
// success for a dropped audit event.
pending.Completion.TrySetException(
new ObjectDisposedException(nameof(SiteEventLogger),
@@ -265,7 +265,7 @@ public class SiteEventLogger : ISiteEventLogger, IDisposable
}
catch (Exception ex)
{
// SiteEventLogging-008: a write failure must be observable. Count it
// A write failure must be observable. Count it
// (Health Monitoring reads FailedWriteCount) and fault the caller's
// Task instead of silently discarding the exception.
Interlocked.Increment(ref _failedWriteCount);