docs: add XML doc comments across src + Sister Projects section in CLAUDE.md

Bulk CommentChecker pass: fills in <param>/<inheritdoc> tags on public
APIs across all 23 src/ projects so the doc-coverage gate is green. Also
adds a Sister Projects section to CLAUDE.md pointing at the MxAccess
Gateway and OtOpcUa sibling repos, and gitignores local credential
captures (*login*.txt) and the wonder-app-vd03 deploy/ artifacts.
This commit is contained in:
Joseph Doherty
2026-05-28 01:55:24 -04:00
parent 6731845473
commit 1eb6e972b0
381 changed files with 5788 additions and 532 deletions
@@ -22,6 +22,11 @@ public class ValidationService
private readonly SemanticValidator _semanticValidator;
private readonly ScriptCompiler _scriptCompiler;
/// <summary>
/// Initializes a new instance of the ValidationService with the specified dependencies.
/// </summary>
/// <param name="semanticValidator">The semantic validator for configuration validation.</param>
/// <param name="scriptCompiler">The script compiler for validating script code.</param>
public ValidationService(SemanticValidator semanticValidator, ScriptCompiler scriptCompiler)
{
_semanticValidator = semanticValidator;
@@ -38,6 +43,8 @@ public class ValidationService
/// <summary>
/// Runs the full validation pipeline on a flattened configuration.
/// </summary>
/// <param name="configuration">The flattened configuration to validate.</param>
/// <param name="sharedScripts">Optional list of shared scripts for validation context.</param>
public ValidationResult Validate(FlattenedConfiguration configuration, IReadOnlyList<ResolvedScript>? sharedScripts = null)
{
ArgumentNullException.ThrowIfNull(configuration);
@@ -60,6 +67,7 @@ public class ValidationService
/// <summary>
/// Validates that flattening produced a non-empty configuration.
/// </summary>
/// <param name="configuration">The flattened configuration to validate.</param>
public static ValidationResult ValidateFlatteningSuccess(FlattenedConfiguration configuration)
{
var errors = new List<ValidationEntry>();
@@ -88,6 +96,7 @@ public class ValidationService
/// Validates that there are no naming collisions across entity types.
/// Canonical names must be unique within their entity type (attributes, alarms, scripts).
/// </summary>
/// <param name="configuration">The flattened configuration to validate.</param>
public static ValidationResult ValidateNamingCollisions(FlattenedConfiguration configuration)
{
var errors = new List<ValidationEntry>();
@@ -104,6 +113,7 @@ public class ValidationService
/// <summary>
/// Validates that all scripts compile successfully using the ScriptCompiler.
/// </summary>
/// <param name="configuration">The flattened configuration to validate.</param>
public ValidationResult ValidateScriptCompilation(FlattenedConfiguration configuration)
{
var errors = new List<ValidationEntry>();
@@ -127,6 +137,7 @@ public class ValidationService
/// Validates that alarm trigger configurations reference existing attributes.
/// Alarm trigger configs are JSON with an "attributeName" field referencing a canonical attribute name.
/// </summary>
/// <param name="configuration">The flattened configuration to validate.</param>
public static ValidationResult ValidateAlarmTriggerReferences(FlattenedConfiguration configuration)
{
var errors = new List<ValidationEntry>();
@@ -155,6 +166,7 @@ public class ValidationService
/// <summary>
/// Validates that script trigger configurations reference existing attributes.
/// </summary>
/// <param name="configuration">The flattened configuration to validate.</param>
public static ValidationResult ValidateScriptTriggerReferences(FlattenedConfiguration configuration)
{
var errors = new List<ValidationEntry>();
@@ -196,6 +208,7 @@ public class ValidationService
/// <see cref="ValidateScriptTriggerReferences"/> for the structured triggers.</item>
/// </list>
/// </summary>
/// <param name="configuration">The flattened configuration to validate.</param>
public static ValidationResult ValidateExpressionTriggers(FlattenedConfiguration configuration)
{
var errors = new List<ValidationEntry>();
@@ -288,6 +301,7 @@ public class ValidationService
/// Reads the "expression" string from a <c>{ "expression": "..." }</c> trigger
/// configuration. Returns <c>null</c> on malformed JSON or a missing key.
/// </summary>
/// <param name="triggerConfigJson">The trigger configuration JSON to parse.</param>
internal static string? ExtractExpressionFromTriggerConfig(string? triggerConfigJson)
{
if (string.IsNullOrWhiteSpace(triggerConfigJson))
@@ -315,6 +329,7 @@ public class ValidationService
/// brackets/quotes. Returns an error message, or <c>null</c> when the expression
/// looks well-formed.
/// </summary>
/// <param name="expression">The expression to check for syntax errors.</param>
internal static string? CheckExpressionSyntax(string expression)
{
// Advisory forbidden-API scan (TemplateEngine-006): code-region-aware so
@@ -423,6 +438,7 @@ public class ValidationService
/// Best-effort: only matches double-quoted literals (the form the editor emits)
/// and skips keys built dynamically.
/// </summary>
/// <param name="expression">The expression to scan for attribute references.</param>
internal static IEnumerable<string> ExtractAttributeReferences(string expression)
{
var seen = new HashSet<string>(StringComparer.Ordinal);
@@ -473,6 +489,7 @@ public class ValidationService
/// <summary>
/// Validates that all data-sourced attributes have connection bindings.
/// </summary>
/// <param name="configuration">The flattened configuration to validate.</param>
public static ValidationResult ValidateConnectionBindingCompleteness(FlattenedConfiguration configuration)
{
var errors = new List<ValidationEntry>();
@@ -510,6 +527,10 @@ public class ValidationService
}
}
/// <summary>
/// Extracts the attribute name from a trigger configuration JSON.
/// </summary>
/// <param name="triggerConfigJson">The trigger configuration JSON to parse.</param>
internal static string? ExtractAttributeNameFromTriggerConfig(string triggerConfigJson)
{
// Accept both keys to stay consistent with FlatteningService.PrefixTriggerAttribute,
@@ -536,6 +557,7 @@ public class ValidationService
/// all-nulls on malformed JSON — callers should treat that as "nothing to
/// validate" and let other checks surface the deeper problem.
/// </summary>
/// <param name="triggerConfigJson">The trigger configuration JSON to parse.</param>
internal static HiLoSetpoints ExtractHiLoSetpoints(string triggerConfigJson)
{
try