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

docs(src): fix CommentChecker findings across src/ — 1,032 → 5 (all false positives)

Browse Source 
Comment/XML-doc changes only, no code logic:
- strip project-tracking references (WP*, P*-*, row-NN, #NN, Task N) from
  comments, keeping the explanatory rationale
- add missing summaries, <param>, <returns>, <typeparam> and <inheritdoc/>
- replace misused <inheritdoc/> with real docs; where <inheritdoc/> was
  combined with useful remarks, move the rationale into // comments
- drop stale replicationActor <param> on DeploymentManagerActor ctor

Remaining 5 are false positives (CWE-1236 x2, failures-1, year-0001, M365).
Build 0 errors / 0 warnings.
This commit is contained in:
Joseph Doherty
2026-10-07 14:12:25 -04:00
parent 3a217b9484
commit 0ffd4bdbea
217 changed files with 1224 additions and 695 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/ZB.MOM.WW.ScadaBridge.ScriptAnalysis/FlowShapePredictor.cs
+43 -9
View File
@@ -45,7 +45,7 @@ public sealed record PredictedFlow(IReadOnlyList<PredictedNode> Nodes, IReadOnly
/// script API exposes (<c>Route.To(x).Call(y)</c>, <c>Scripts.Call(y)</c>,
/// <c>….Attributes.WriteBatchAndWaitAsync(…)</c>, <c>….Attributes[x] = v</c>, …) by text with
/// whitespace stripped, exactly as <see cref="ScriptTrustValidator"/>'s hardening walker does.
/// The nine-argument reset-aware <c>WriteBatchAndWaitAsync</c> overload (Gitea #36) additionally
/// The nine-argument reset-aware <c>WriteBatchAndWaitAsync</c> overload additionally
/// predicts a reset attribute write + echo wait ahead of the batch write + wait pair.
/// String-literal arguments resolve to titles; anything else is flagged
/// <see cref="PredictedNode.InputDependent"/>. Branching is not modelled: every recognised call
@@ -83,6 +83,7 @@ public static class FlowShapePredictor
/// known expression, and a test resolver may answer for anything).
/// </param>
/// <param name="maxDepth">Recursion cap; nested script bodies beyond it are not expanded.</param>
/// <returns>The predicted flow, degraded to a request/response pair when the script cannot be parsed.</returns>
public static PredictedFlow PredictInboundMethod(
string methodName,
string methodScript,
@@ -117,6 +118,7 @@ public static class FlowShapePredictor
/// <param name="scriptName">The script name (titles the root node).</param>
/// <param name="scriptBody">The script's C# body.</param>
/// <param name="maxDepth">Recursion cap.</param>
/// <returns>The predicted flow of the site script.</returns>
public static PredictedFlow PredictSiteScript(string scriptName, string scriptBody, int maxDepth = DefaultMaxDepth)
{
var b = new Builder((_, _) => null, Math.Max(1, maxDepth));
@@ -146,20 +148,32 @@ public static class FlowShapePredictor
private string? _previous;
private string? _pendingNote;
/// <summary>Initializes the builder.</summary>
/// <param name="resolve">Resolves <c>(instanceCode, scriptName)</c> to a script body, or null.</param>
/// <param name="maxDepth">Recursion cap for nested script expansion.</param>
internal Builder(Func<string, string, string?> resolve, int maxDepth)
{
_resolve = resolve;
_maxDepth = maxDepth;
}
/// <summary>Snapshots the accumulated nodes and edges into a <see cref="PredictedFlow"/>.</summary>
/// <returns>The predicted flow built so far.</returns>
internal PredictedFlow Build() => new(_nodes.ToArray(), _edges.ToArray());
/// <summary>
/// Adds a node, chains it to the previous one, and consumes any pending early-return note.
/// An <paramref name="async"/> node hangs off the previous node on an <see cref="PredictedEdge.Async"/>
/// edge and does NOT become the new chain head — the next node still links from the previous
/// non-async node (D4: a cached call or notification returns immediately, so the run continues without it).
/// non-async node (a cached call or notification returns immediately, so the run continues without it).
/// </summary>
/// <param name="kind">The kind of step the node represents.</param>
/// <param name="lane">The swimlane the node belongs to.</param>
/// <param name="title">The node title.</param>
/// <param name="inputDependent">True when the title could not be resolved from a literal.</param>
/// <param name="note">An optional note for the node.</param>
/// <param name="async">True when the node hangs off the chain on an async edge.</param>
/// <returns>The id of the new node.</returns>
internal string AddNode(FlowStepKind kind, FlowLane lane, string title, bool inputDependent, string? note, bool async = false)
{
var id = "n" + (_nodes.Count + 1).ToString(CultureInfo.InvariantCulture);
@@ -180,6 +194,9 @@ public static class FlowShapePredictor
return id;
}
/// <summary>Appends a note to an existing node.</summary>
/// <param name="id">The id of the node to annotate.</param>
/// <param name="note">The note to append.</param>
internal void Annotate(string id, string note)
{
var i = _nodes.FindIndex(n => n.Id == id);
@@ -189,6 +206,7 @@ public static class FlowShapePredictor
}
/// <summary>Drops everything after the first <paramref name="keep"/> nodes (fault recovery).</summary>
/// <param name="keep">The number of leading nodes to keep.</param>
internal void Reset(int keep)
{
if (_nodes.Count > keep) _nodes.RemoveRange(keep, _nodes.Count - keep);
@@ -202,6 +220,11 @@ public static class FlowShapePredictor
/// Walks one script body in the given lane. Returns false when the body has parse
/// errors (nothing is emitted for it), true otherwise.
/// </summary>
/// <param name="code">The script body to parse and walk.</param>
/// <param name="lane">The lane the body runs in.</param>
/// <param name="instanceCode">The target instance code, or null.</param>
/// <param name="depth">The current recursion depth.</param>
/// <returns><c>false</c> when the body has parse errors; otherwise <c>true</c>.</returns>
internal bool Walk(string code, FlowLane lane, string? instanceCode, int depth)
{
var tree = CSharpSyntaxTree.ParseText(code, new CSharpParseOptions(kind: SourceCodeKind.Script));
@@ -213,10 +236,15 @@ public static class FlowShapePredictor
return true;
}
/// <summary>Queues a note to attach to the next node added.</summary>
/// <param name="note">The note text.</param>
internal void QueueNote(string note)
=> _pendingNote = _pendingNote == null ? note : $"{_pendingNote}; {note}";
/// <summary>Expands a routed / nested script call one level, if the resolver can supply its body.</summary>
/// <param name="instanceCode">The target instance code (or its source text).</param>
/// <param name="scriptName">The name of the script to expand.</param>
/// <param name="depth">The current recursion depth.</param>
internal void ExpandScript(string instanceCode, string scriptName, int depth)
{
if (depth >= _maxDepth)
@@ -251,6 +279,11 @@ public static class FlowShapePredictor
private readonly string? _instanceCode;
private readonly int _depth;
/// <summary>Initializes the walker.</summary>
/// <param name="b">The builder that receives nodes.</param>
/// <param name="lane">The lane the walked body runs in.</param>
/// <param name="instanceCode">The target instance code, or null.</param>
/// <param name="depth">The current recursion depth.</param>
internal Walker(Builder b, FlowLane lane, string? instanceCode, int depth)
{
_b = b;
@@ -261,12 +294,11 @@ public static class FlowShapePredictor
private static string Strip(string text) => new(text.Where(c => !char.IsWhiteSpace(c)).ToArray());
/// <summary>
/// An <c>if (…) { … return …; }</c> guard becomes a note on the node that FOLLOWS it.
/// The condition is visited first (it may itself contain a traced call — the Delmia
/// site script's <c>if (!await …WriteBatchAndWaitAsync(…)) return …</c>), then the
/// body, and only then is the note queued for whatever comes next.
/// </summary>
// An `if (…) { … return …; }` guard becomes a note on the node that FOLLOWS it.
// The condition is visited first (it may itself contain a traced call — the Delmia
// site script's `if (!await …WriteBatchAndWaitAsync(…)) return …`), then the
// body, and only then is the note queued for whatever comes next.
/// <inheritdoc />
public override void VisitIfStatement(IfStatementSyntax node)
{
Visit(node.Condition);
@@ -280,6 +312,7 @@ public static class FlowShapePredictor
_b.QueueNote($"early return: {Condense(node.Condition.ToString())}");
}
/// <inheritdoc />
public override void VisitAssignmentExpression(AssignmentExpressionSyntax node)
{
// recv.Attributes["X"] = v / Attributes["X"] = v
@@ -294,6 +327,7 @@ public static class FlowShapePredictor
base.VisitAssignmentExpression(node);
}
/// <inheritdoc />
public override void VisitInvocationExpression(InvocationExpressionSyntax node)
{
// Visit inner invocations first? No — source order for a chained call like
@@ -372,7 +406,7 @@ public static class FlowShapePredictor
case "WriteBatchAndWaitAsync":
{
// (batch, triggerAttr, triggerValue, waitAttr, waitValue, timeout
// [, resetAttr, resetValue, resetTimeout]) — Gitea #36: the reset-aware
// [, resetAttr, resetValue, resetTimeout]) — the reset-aware
// overload writes + waits on the reset attribute BEFORE the batch.
var (trigger, triggerDependent) = LiteralOrExpr(args.ElementAtOrDefault(1)?.Expression);
var (wait, waitDependent) = LiteralOrExpr(args.ElementAtOrDefault(3)?.Expression);
src/ZB.MOM.WW.ScadaBridge.ScriptAnalysis/ScriptCompileSurface.cs
+1 -1
View File
@@ -373,7 +373,7 @@ public sealed class ScriptCompileSurface
/// <returns><c>true</c> if the response value was observed before the timeout elapsed; otherwise <c>false</c>.</returns>
public Task<bool> WriteBatchAndWaitAsync(IReadOnlyDictionary<string, object?> values, string flagKey, object? flagValue, string responseKey, object? responseValue, TimeSpan timeout) => throw new NotSupportedException(CompileOnly);
/// <summary>Mirrors the reset-aware <c>AttributeAccessor.WriteBatchAndWaitAsync</c> overload (Gitea #36).</summary>
/// <summary>Mirrors the reset-aware <c>AttributeAccessor.WriteBatchAndWaitAsync</c> overload.</summary>
/// <param name="values">The set of attribute values to write as a batch.</param>
/// <param name="flagKey">The name of the flag attribute signaling the write.</param>
/// <param name="flagValue">The value written to the flag attribute.</param>