Merge pull request #220 from erikdarlingdata/dev

Release v1.5.0 — maximum benefit scoring

Author: erikdarlingdata

src/PlanViewer.App/Controls/PlanViewerControl.axaml.cs

@@ -275,6 +275,7 @@ public void LoadPlan(string planXml, string label, string? queryText = null)
 
         _currentPlan = ShowPlanParser.Parse(planXml);
         PlanAnalyzer.Analyze(_currentPlan, ConfigLoader.Load());
+        BenefitScorer.Score(_currentPlan);
 
         var allStatements = _currentPlan.Batches
             .SelectMany(b => b.Statements)
@@ -1725,14 +1726,21 @@ private void ShowPropertiesPanel(PlanNode node)
             if (s.PlanWarnings.Count > 0)
             {
                 var planWarningsPanel = new StackPanel();
-                foreach (var w in s.PlanWarnings)
+                var sortedPlanWarnings = s.PlanWarnings
+                    .OrderByDescending(w => w.MaxBenefitPercent ?? -1)
+                    .ThenByDescending(w => w.Severity)
+                    .ThenBy(w => w.WarningType);
+                foreach (var w in sortedPlanWarnings)
                 {
                     var warnColor = w.Severity == PlanWarningSeverity.Critical ? "#E57373"
                         : w.Severity == PlanWarningSeverity.Warning ? "#FFB347" : "#6BB5FF";
                     var warnPanel = new StackPanel { Margin = new Thickness(10, 2, 10, 2) };
+                    var planWarnHeader = w.MaxBenefitPercent.HasValue
+                        ? $"\u26A0 {w.WarningType} \u2014 up to {w.MaxBenefitPercent:N0}% benefit"
+                        : $"\u26A0 {w.WarningType}";
                     warnPanel.Children.Add(new TextBlock
                     {
-                        Text = $"\u26A0 {w.WarningType}",
+                        Text = planWarnHeader,
                         FontWeight = FontWeight.SemiBold,
                         FontSize = 11,
                         Foreground = new SolidColorBrush(Color.Parse(warnColor))
@@ -1788,14 +1796,21 @@ private void ShowPropertiesPanel(PlanNode node)
         if (node.HasWarnings)
         {
             var warningsPanel = new StackPanel();
-            foreach (var w in node.Warnings)
+            var sortedNodeWarnings = node.Warnings
+                .OrderByDescending(w => w.MaxBenefitPercent ?? -1)
+                .ThenByDescending(w => w.Severity)
+                .ThenBy(w => w.WarningType);
+            foreach (var w in sortedNodeWarnings)
             {
                 var warnColor = w.Severity == PlanWarningSeverity.Critical ? "#E57373"
                     : w.Severity == PlanWarningSeverity.Warning ? "#FFB347" : "#6BB5FF";
                 var warnPanel = new StackPanel { Margin = new Thickness(10, 2, 10, 2) };
+                var nodeWarnHeader = w.MaxBenefitPercent.HasValue
+                    ? $"\u26A0 {w.WarningType} \u2014 up to {w.MaxBenefitPercent:N0}% benefit"
+                    : $"\u26A0 {w.WarningType}";
                 warnPanel.Children.Add(new TextBlock
                 {
-                    Text = $"\u26A0 {w.WarningType}",
+                    Text = nodeWarnHeader,
                     FontWeight = FontWeight.SemiBold,
                     FontSize = 11,
                     Foreground = new SolidColorBrush(Color.Parse(warnColor))
@@ -2140,18 +2155,21 @@ private object BuildNodeTooltipContent(PlanNode node, List<PlanWarning>? allWarn
 
             if (allWarnings != null)
             {
-                // Root node: show distinct warning type names only
+                // Root node: show distinct warning type names only, sorted by max benefit
                 var distinct = warnings
                     .GroupBy(w => w.WarningType)
-                    .Select(g => (Type: g.Key, MaxSeverity: g.Max(w => w.Severity), Count: g.Count()))
-                    .OrderByDescending(g => g.MaxSeverity)
+                    .Select(g => (Type: g.Key, MaxSeverity: g.Max(w => w.Severity), Count: g.Count(),
+                                  MaxBenefit: g.Max(w => w.MaxBenefitPercent ?? -1)))
+                    .OrderByDescending(g => g.MaxBenefit)
+                    .ThenByDescending(g => g.MaxSeverity)
                     .ThenBy(g => g.Type);
 
-                foreach (var (type, severity, count) in distinct)
+                foreach (var (type, severity, count, maxBenefit) in distinct)
                 {
                     var warnColor = severity == PlanWarningSeverity.Critical ? "#E57373"
                         : severity == PlanWarningSeverity.Warning ? "#FFB347" : "#6BB5FF";
-                    var label = count > 1 ? $"\u26A0 {type} ({count})" : $"\u26A0 {type}";
+                    var benefitSuffix = maxBenefit >= 0 ? $" \u2014 up to {maxBenefit:N0}%" : "";
+                    var label = count > 1 ? $"\u26A0 {type} ({count}){benefitSuffix}" : $"\u26A0 {type}{benefitSuffix}";
                     stack.Children.Add(new TextBlock
                     {
                         Text = label,

src/PlanViewer.App/Mcp/McpQueryStoreTools.cs

@@ -124,6 +124,7 @@ public static async Task<string> GetQueryStoreTop(
                         .Replace("encoding=\"utf-16\"", "encoding=\"utf-8\"");
                     var parsed = ShowPlanParser.Parse(xml);
                     PlanAnalyzer.Analyze(parsed);
+                    BenefitScorer.Score(parsed);
 
                     var allStatements = parsed.Batches.SelectMany(b => b.Statements).ToList();
 

src/PlanViewer.App/PlanViewer.App.csproj

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

src/PlanViewer.App/Services/AdviceContentBuilder.cs

@@ -7,6 +7,7 @@
 using Avalonia.Layout;
 using Avalonia.Media;
 using PlanViewer.Core.Output;
+using PlanViewer.Core.Services;
 
 namespace PlanViewer.App.Services;
 
@@ -994,6 +995,12 @@ private static StackPanel CreateWaitStatLine(string waitName, string waitValue,
         var waitBrush = GetWaitCategoryBrush(waitName);
         tb.Inlines!.Add(new Run(waitName) { Foreground = waitBrush });
         tb.Inlines.Add(new Run(": " + waitValue) { Foreground = ValueBrush });
+
+        // Inline description label for the wait type
+        var label = PlanAnalyzer.GetWaitLabel(waitName);
+        if (!string.IsNullOrEmpty(label))
+            tb.Inlines.Add(new Run("  " + label) { Foreground = MutedBrush, FontSize = 11 });
+
         wrapper.Children.Add(tb);
 
         // Proportional bar scaled to max wait in group
@@ -1119,6 +1126,41 @@ private static SolidColorBrush GetWaitCategoryBrush(string waitType)
             items.Add(($"Memory grant: {grantedMB:F1} MB ({usedPct:F0}% used)", memBrush));
         }
 
+        // Wait profile classification
+        if (stmt.WaitStats.Count > 0)
+        {
+            var totalMs = stmt.WaitStats.Sum(w => w.WaitTimeMs);
+            if (totalMs > 0)
+            {
+                long ioMs = 0, cpuMs = 0, parallelMs = 0, lockMs = 0;
+                foreach (var w in stmt.WaitStats)
+                {
+                    var wt = w.WaitType.ToUpperInvariant();
+                    if (wt.StartsWith("PAGEIOLATCH") || wt.Contains("IO_COMPLETION"))
+                        ioMs += w.WaitTimeMs;
+                    else if (wt == "SOS_SCHEDULER_YIELD")
+                        cpuMs += w.WaitTimeMs;
+                    else if (wt.StartsWith("CX"))
+                        parallelMs += w.WaitTimeMs;
+                    else if (wt.StartsWith("LCK_"))
+                        lockMs += w.WaitTimeMs;
+                }
+
+                // Pick the dominant category (>= 30% of total)
+                var categories = new List<(string label, long ms)>();
+                if (ioMs * 100 / totalMs >= 30) categories.Add(("I/O", ioMs));
+                if (cpuMs * 100 / totalMs >= 30) categories.Add(("CPU", cpuMs));
+                if (parallelMs * 100 / totalMs >= 30) categories.Add(("parallelism", parallelMs));
+                if (lockMs * 100 / totalMs >= 30) categories.Add(("lock contention", lockMs));
+
+                if (categories.Count > 0)
+                {
+                    var label = string.Join(" + ", categories.Select(c => c.label));
+                    items.Add(($"{label} bound ({totalMs:N0}ms total wait time)", InfoBrush));
+                }
+            }
+        }
+
         // Warning counts by severity
         var criticalCount = stmt.Warnings.Count(w =>
             w.Severity.Equals("Critical", StringComparison.OrdinalIgnoreCase));

src/PlanViewer.Cli/Commands/AnalyzeCommand.cs

@@ -207,6 +207,7 @@ private static async Task RunAsync(FileInfo? file, bool stdin, string output, bo
 
         var plan = ShowPlanParser.Parse(planXml);
         PlanAnalyzer.Analyze(plan, analyzerConfig);
+        BenefitScorer.Score(plan);
 
         if (plan.Batches.Count == 0)
         {
@@ -400,6 +401,7 @@ private static async Task RunLiveAsync(
                 // Parse, analyze, map result
                 var plan = ShowPlanParser.Parse(planXml);
                 PlanAnalyzer.Analyze(plan, analyzerConfig);
+                BenefitScorer.Score(plan);
                 var result = ResultMapper.Map(plan, $"{name}.sql");
 
                 if (warningsOnly)

src/PlanViewer.Cli/Commands/QueryStoreCommand.cs

@@ -273,6 +273,7 @@ private static async Task RunAsync(
                 // Parse, analyze, map
                 var plan = ShowPlanParser.Parse(qsPlan.PlanXml);
                 PlanAnalyzer.Analyze(plan, analyzerConfig);
+                BenefitScorer.Score(plan);
                 var result = ResultMapper.Map(plan, $"{label}.sqlplan");
 
                 if (warningsOnly)

src/PlanViewer.Core/Models/PlanModels.cs

@@ -373,6 +373,17 @@ public class PlanWarning
     public string Message { get; set; } = "";
     public PlanWarningSeverity Severity { get; set; }
     public SpillDetail? SpillDetails { get; set; }
+
+    /// <summary>
+    /// Maximum percentage of elapsed time that could be saved by addressing this finding.
+    /// null = not quantifiable, 0 = calculated as negligible.
+    /// </summary>
+    public double? MaxBenefitPercent { get; set; }
+
+    /// <summary>
+    /// Short actionable fix suggestion (e.g., "Add INCLUDE (columns) to index").
+    /// </summary>
+    public string? ActionableFix { get; set; }
 }
 
 public enum PlanWarningSeverity { Info, Warning, Critical }

src/PlanViewer.Core/Output/AnalysisResult.cs

@@ -208,6 +208,12 @@ public class WarningResult
 
     [JsonPropertyName("node_id")]
     public int? NodeId { get; set; }
+
+    [JsonPropertyName("max_benefit_percent")]
+    public double? MaxBenefitPercent { get; set; }
+
+    [JsonPropertyName("actionable_fix")]
+    public string? ActionableFix { get; set; }
 }
 
 public class MissingIndexResult

src/PlanViewer.Core/Output/HtmlExporter.cs

@@ -185,6 +185,7 @@ .card h3 {
 .sev-info { color: var(--info); }
 .warn-op { font-size: 0.75rem; font-weight: 500; color: var(--text-secondary); }
 .warn-type { font-size: 0.75rem; font-weight: 600; }
+.warn-benefit { font-size: 0.7rem; font-weight: 600; color: var(--text-muted); padding: 0.05rem 0.3rem; border-radius: 3px; background: rgba(0,0,0,0.04); }
 .warn-msg { font-size: 0.8rem; color: var(--text); flex-basis: 100%; }
 
 /* Query text */
@@ -428,14 +429,22 @@ private static void WriteWarnings(StringBuilder sb, StatementResult stmt)
         if (infoCount > 0) sb.Append($" <span class=\"warn-badge info\">{infoCount}</span>");
         sb.AppendLine("</h3>");
 
-        foreach (var w in allWarnings)
+        // Sort by benefit descending (nulls last), then severity, then type
+        var sorted = allWarnings
+            .OrderByDescending(w => w.MaxBenefitPercent ?? -1)
+            .ThenBy(w => w.Severity switch { "Critical" => 0, "Warning" => 1, _ => 2 })
+            .ThenBy(w => w.Type);
+
+        foreach (var w in sorted)
         {
             var sevLower = w.Severity.ToLower();
             sb.AppendLine($"<div class=\"warning-item {sevLower}\">");
             sb.AppendLine($"<span class=\"sev sev-{sevLower}\">{Encode(w.Severity)}</span>");
             if (w.Operator != null)
                 sb.AppendLine($"<span class=\"warn-op\">{Encode(w.Operator)}</span>");
             sb.AppendLine($"<span class=\"warn-type\">{Encode(w.Type)}</span>");
+            if (w.MaxBenefitPercent.HasValue)
+                sb.AppendLine($"<span class=\"warn-benefit\">up to {w.MaxBenefitPercent:N0}% benefit</span>");
             sb.AppendLine($"<span class=\"warn-msg\">{Encode(w.Message)}</span>");
             sb.AppendLine("</div>");
         }

src/PlanViewer.Core/Output/ResultMapper.cs

@@ -158,7 +158,9 @@ private static StatementResult MapStatement(PlanStatement stmt)
             {
                 Type = w.WarningType,
                 Severity = w.Severity.ToString(),
-                Message = w.Message
+                Message = w.Message,
+                MaxBenefitPercent = w.MaxBenefitPercent,
+                ActionableFix = w.ActionableFix
             });
         }
 
@@ -259,7 +261,9 @@ private static OperatorResult MapNode(PlanNode node)
                 Severity = w.Severity.ToString(),
                 Message = w.Message,
                 Operator = $"{node.PhysicalOp} (Node {node.NodeId})",
-                NodeId = node.NodeId
+                NodeId = node.NodeId,
+                MaxBenefitPercent = w.MaxBenefitPercent,
+                ActionableFix = w.ActionableFix
             });
         }