feat(cli+templateengine+deploymanager): resolve follow-ups #4/#5/#6/#8 — CLI ergonomics + structured deploy validation error

Closes the four remaining items in the 2026-06-24 template-inheritance/CLI
follow-up tracker.

#4 — CLI `instance set-bindings` can now set DataSourceReferenceOverride.
  `--bindings` accepts an optional 3rd element per entry:
  [attributeName, dataConnectionId, dataSourceReferenceOverride]. A string
  sets the override; a JSON null or an omitted 3rd element leaves it unset
  (template default). TryParseBindings accepts 2- or 3-element entries and
  rejects a non-string/non-null 3rd element or 4+ elements with a clean
  error. Previously the CLI sent the override as null and silently wiped any
  existing one (only a raw POST /management could set it).

#5 — `template update` is partial, not full-replace (fixed server-side so all
  clients benefit). UpdateTemplateAsync now uses leave-unchanged semantics:
  a null description keeps the stored value (pass "" to clear); a null
  parentTemplateId keeps the existing parent. Parent stays immutable — a
  non-null differing value is still rejected — but omitting --parent-id is
  now a no-op instead of failing every derived-template update.

#6 — compact `template list`/`get` table output + `--detail`. Table output is
  now id/name/description/parent/derived + member counts (#attrs/#alarms/
  #scripts/#comps/#nativeAlarms) via TemplateTableProjection, fed through a
  new optional tableProjector seam on CommandHelpers. `--detail` restores the
  full dump. JSON output is left untouched (always full) so machine consumers
  are unaffected — the projector only runs on the table path.

#8 — structured deploy-time validation error. New ValidationResult.SummarizeErrors()
  (Commons) returns a grouped, capped summary: leading total count, one line
  per ValidationCategory, and a per-module rollup (canonical name up to its
  last dot) with counts + "... and N more module(s)" caps. DeploymentService
  uses it for the "Pre-deployment validation failed" message and logs the full
  per-entry list via LogWarning. Replaces the flat semicolon-joined dump that
  became a wall of text for instances with 50-194 unbound attributes.

Tests: +8 Commons (SummarizeErrors), +8 CLI (4 binding 3-element / 4 table
projection), +2 net TemplateEngine (partial-update). Affected suites green:
Commons 587, CLI 341, TemplateEngine 447, DeploymentManager 101,
ManagementService 230, CentralUI 866; full solution builds 0/0.

Docs: Component-DeploymentManager.md "Validation Error Reporting"; CLI README
(set-bindings 3-element form, template update leave-unchanged, list/get
--detail); UpdateTemplateCommand doc; known-issues tracker #4/#5/#6/#8 resolved
(all 8 items now closed).
This commit is contained in:
Joseph Doherty
2026-06-24 18:27:42 -04:00
parent 2b5949320c
commit cdd65beb6c
15 changed files with 745 additions and 54 deletions
@@ -3,6 +3,13 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
public record ListTemplatesCommand;
public record GetTemplateCommand(int TemplateId);
public record CreateTemplateCommand(string Name, string? Description, int? ParentTemplateId);
/// <summary>
/// Updates a template. Optional fields use leave-unchanged semantics (followup #5):
/// a <c>null</c> <see cref="Description"/> keeps the stored description (pass an empty
/// string to clear it), and a <c>null</c> <see cref="ParentTemplateId"/> keeps the
/// existing parent (the parent is immutable; a non-null value that differs is rejected).
/// </summary>
public record UpdateTemplateCommand(int TemplateId, string Name, string? Description, int? ParentTemplateId);
public record DeleteTemplateCommand(int TemplateId);
public record ValidateTemplateCommand(int TemplateId);
@@ -1,3 +1,5 @@
using System.Text;
namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Flattening;
/// <summary>
@@ -12,6 +14,98 @@ public sealed record ValidationResult
/// <summary>Non-blocking validation warnings.</summary>
public IReadOnlyList<ValidationEntry> Warnings { get; init; } = [];
/// <summary>
/// Produces a compact, human-readable summary of the validation errors instead of a
/// flat semicolon-joined dump (followup #8). The old behaviour concatenated one clause
/// per error — for an instance with 50194 unbound attributes that is a wall of text
/// unreadable in a CLI/UI toast. This groups errors by <see cref="ValidationCategory"/>
/// and, within a category, rolls entries up by "module" (the entity's canonical name up
/// to its last dot) with counts, capping the breadth with "… and N more". The full,
/// per-entry list is still available on <see cref="Errors"/> for a detail view or log.
/// </summary>
/// <param name="maxGroups">
/// Maximum number of modules (or messages, when entries are not entity-scoped) to list
/// per category before collapsing the remainder into a "… and N more" suffix.
/// </param>
/// <returns>
/// A multi-line summary, or an empty string when there are no errors. The first line is
/// the total error count; subsequent lines are one per category.
/// </returns>
public string SummarizeErrors(int maxGroups = 6)
{
if (Errors.Count == 0)
return string.Empty;
var sb = new StringBuilder();
sb.Append(Errors.Count).Append(Errors.Count == 1 ? " error:" : " errors:");
// Group errors by category, preserving first-seen order for a stable rendering.
var byCategory = new List<(ValidationCategory Category, List<ValidationEntry> Items)>();
var categoryIndex = new Dictionary<ValidationCategory, int>();
foreach (var error in Errors)
{
if (!categoryIndex.TryGetValue(error.Category, out var i))
{
i = byCategory.Count;
categoryIndex[error.Category] = i;
byCategory.Add((error.Category, []));
}
byCategory[i].Items.Add(error);
}
foreach (var (category, items) in byCategory)
{
sb.AppendLine();
sb.Append(" • ").Append(category).Append(" (").Append(items.Count).Append("): ");
// Prefer an entity/module rollup when every entry names an entity (the unbound-
// binding case). Otherwise fall back to a capped list of the raw messages.
if (items.TrueForAll(e => !string.IsNullOrEmpty(e.EntityName)))
{
var modules = new List<(string Module, int Count)>();
var moduleIndex = new Dictionary<string, int>(StringComparer.Ordinal);
foreach (var entry in items)
{
var module = ModuleOf(entry.EntityName!);
if (!moduleIndex.TryGetValue(module, out var mi))
{
mi = modules.Count;
moduleIndex[module] = mi;
modules.Add((module, 0));
}
modules[mi] = (module, modules[mi].Count + 1);
}
var shown = modules.Take(maxGroups).Select(m => $"{m.Module} ({m.Count})");
sb.Append(string.Join(", ", shown));
if (modules.Count > maxGroups)
sb.Append($", … and {modules.Count - maxGroups} more module(s)");
}
else
{
var shown = items.Take(maxGroups).Select(e => e.Message);
sb.Append(string.Join("; ", shown));
if (items.Count > maxGroups)
sb.Append($"; … and {items.Count - maxGroups} more");
}
}
return sb.ToString();
}
/// <summary>
/// Returns the "module" portion of a canonical attribute name — everything up to the
/// last <c>.</c> (e.g. <c>LeftReactorSide.LeakTest.DeltaVac</c> → <c>LeftReactorSide.LeakTest</c>).
/// A name with no dot is reported under <c>(root)</c>.
/// </summary>
/// <param name="canonicalName">The entity's canonical name.</param>
/// <returns>The module prefix, or <c>(root)</c> for top-level members.</returns>
private static string ModuleOf(string canonicalName)
{
var lastDot = canonicalName.LastIndexOf('.');
return lastDot > 0 ? canonicalName[..lastDot] : "(root)";
}
/// <summary>Returns a result with no errors or warnings.</summary>
/// <returns>A <see cref="ValidationResult"/> with empty error and warning lists.</returns>
public static ValidationResult Success() => new();