Wait stats as warnings (#215, Joe feedback a1/b4/b5) (#244)

Each wait stat recorded on a statement now emits a first-class PlanWarning
alongside the existing wait-stats card, so waits sort by benefit % in the
warnings list next to operator findings instead of living only in their own
panel.

- WaitStatsKnowledge: per-wait description + how-to-fix content covering
  PAGEIOLATCH_*, PAGELATCH_*, LATCH_*, LCK_M_*, MEMORY_ALLOCATION_EXT,
  RESOURCE_SEMAPHORE*, CX*/HT*/BMPBUILD parallel + batch-mode families,
  SOS_SCHEDULER_YIELD, THREADPOOL, ASYNC_NETWORK_IO, WRITELOG, IO_COMPLETION,
  LOGBUFFER, EXECSYNC, PREEMPTIVE_OS_WRITEFILEGATHER, with prefix fallbacks.
- PAGEIOLATCH_SH/EX/UP/DT warnings include effective latency per wait
  (wait_ms / wait_count) in the message.
- Severity tiers off benefit %: >=50 Critical, >=10 Warning, else Info.
- Flows through existing PlanWarnings pipeline so web viewer, HTML export,
  JSON/text, and Avalonia Plan Warnings expander all pick it up with no
  renderer changes. Wait-stats chart stays as a complementary view.
- Version bump 1.6.0 -> 1.7.0.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: erikdarlingdata

src/PlanViewer.App/PlanViewer.App.csproj

@@ -6,7 +6,7 @@
     <ApplicationManifest>app.manifest</ApplicationManifest>
     <ApplicationIcon>EDD.ico</ApplicationIcon>
     <AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault>
-    <Version>1.6.0</Version>
+    <Version>1.7.0</Version>
     <Authors>Erik Darling</Authors>
     <Company>Darling Data LLC</Company>
     <Product>Performance Studio</Product>

src/PlanViewer.Core/Services/BenefitScorer.cs

@@ -38,10 +38,73 @@ public static void Score(ParsedPlan plan)
 
                 if (stmt.WaitStats.Count > 0 && stmt.QueryTimeStats != null)
                     ScoreWaitStats(stmt);
+
+                if (stmt.WaitStats.Count > 0)
+                    EmitWaitStatWarnings(stmt);
+            }
+        }
+    }
+
+    /// <summary>
+    /// Emits a PlanWarning per wait stat entry, merging the per-wait benefit %
+    /// from ScoreWaitStats with the descriptive content from WaitStatsKnowledge.
+    /// The existing wait-stats chart/card stays as a complementary view.
+    /// </summary>
+    private static void EmitWaitStatWarnings(PlanStatement stmt)
+    {
+        // Lookup benefit % by wait type (populated by ScoreWaitStats)
+        var benefitByType = new Dictionary<string, double>(StringComparer.OrdinalIgnoreCase);
+        foreach (var wb in stmt.WaitBenefits)
+            benefitByType[wb.WaitType] = wb.MaxBenefitPercent;
+
+        foreach (var wait in stmt.WaitStats)
+        {
+            if (wait.WaitTimeMs <= 0) continue;
+
+            var entry = WaitStatsKnowledge.Lookup(wait.WaitType);
+            double? benefitPct = benefitByType.TryGetValue(wait.WaitType, out var b) ? b : null;
+
+            var msg = new System.Text.StringBuilder();
+            msg.Append(wait.WaitType).Append(": ").Append(entry.Description);
+            msg.Append(" Observed ").Append(wait.WaitTimeMs.ToString("N0")).Append(" ms");
+            if (wait.WaitCount > 0)
+                msg.Append(" across ").Append(wait.WaitCount.ToString("N0")).Append(" wait").Append(wait.WaitCount == 1 ? "" : "s");
+            msg.Append('.');
+
+            if (entry.ShowEffectiveLatency && wait.WaitCount > 0)
+            {
+                var effLatency = (double)wait.WaitTimeMs / wait.WaitCount;
+                msg.Append(" Effective latency: ")
+                   .Append(FormatLatency(effLatency))
+                   .Append(" per wait.");
             }
+
+            var severity = benefitPct switch
+            {
+                >= 50 => PlanWarningSeverity.Critical,
+                >= 10 => PlanWarningSeverity.Warning,
+                _     => PlanWarningSeverity.Info,
+            };
+
+            stmt.PlanWarnings.Add(new PlanWarning
+            {
+                WarningType = "Wait: " + wait.WaitType,
+                Message = msg.ToString(),
+                Severity = severity,
+                MaxBenefitPercent = benefitPct,
+                ActionableFix = entry.HowToFix
+            });
         }
     }
 
+    private static string FormatLatency(double ms)
+    {
+        if (ms >= 1000) return $"{ms / 1000:N2} s";
+        if (ms >= 10)   return $"{ms:N0} ms";
+        if (ms >= 1)    return $"{ms:N1} ms";
+        return $"{ms * 1000:N0} µs";
+    }
+
     private static void ScoreStatementWarnings(PlanStatement stmt)
     {
         var elapsedMs = stmt.QueryTimeStats?.ElapsedTimeMs ?? 0;