ScadaBridge/src/ZB.MOM.WW.ScadaBridge.ScriptAnalysis/FlowShapePredictor.cs

using System.Globalization;
using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;
using Microsoft.CodeAnalysis.CSharp.Syntax;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Debugging;

namespace ZB.MOM.WW.ScadaBridge.ScriptAnalysis;

/// <summary>A node of a predicted flow (Flow Debugger design 2026-09-05 §5.5 — the "Predicted" state).</summary>
/// <param name="Id">Stable id within the flow (<c>n1</c>, <c>n2</c>, …).</param>
/// <param name="Kind">The step kind this node would produce when run.</param>
/// <param name="Lane">The swimlane it is drawn in.</param>
/// <param name="Title">Display title — the route target, script name, attribute name, …</param>
/// <param name="InputDependent">True when the target is computed from inputs (not a string literal) and could not be predicted statically.</param>
/// <param name="Note">Advisory text — an early-return guard that precedes this node, a depth cap, a parse error.</param>
public sealed record PredictedNode(string Id, FlowStepKind Kind, FlowLane Lane, string Title, bool InputDependent, string? Note);

/// <summary>A directed edge between two predicted nodes.</summary>
/// <param name="From">Source node id.</param>
/// <param name="To">Target node id.</param>
/// <param name="CrossesBoundary">True when exactly one end sits in the Central lane (a central↔site hop).</param>
public sealed record PredictedEdge(string From, string To, bool CrossesBoundary);

/// <summary>The predicted shape of a flow: nodes in source order plus the chain edges between them.</summary>
public sealed record PredictedFlow(IReadOnlyList<PredictedNode> Nodes, IReadOnlyList<PredictedEdge> Edges)
{
    /// <summary>An empty prediction.</summary>
    public static readonly PredictedFlow Empty = new([], []);
}

/// <summary>
/// Predicts the shape of an inbound-API or site-script flow from script <em>syntax</em> alone
/// (Flow Debugger design 2026-09-05 §5.5): which routed calls, script calls, attribute writes
/// and attribute waits the script would produce, in source order, before anything runs.
///
/// <para>
/// This is a syntax walk, not a semantic one — it matches the same member-access chains the
/// 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.
/// String-literal arguments resolve to titles; anything else is flagged
/// <see cref="PredictedNode.InputDependent"/>. Branching is not modelled: every recognised call
/// is emitted once in source order, and an <c>if (…) return …;</c> guard that precedes the next
/// node is surfaced as a note on that node. The predicted node kinds are exactly the kinds a
/// traced run records, so the page can overlay the real graph on the prediction by kind + title.
/// </para>
///
/// <para>
/// Kept DB-free on purpose: a caller supplies <c>resolveRouteScript(instanceCode, scriptName)</c>
/// to turn a route target into a site script body (Central UI resolves instance → template →
/// script); this class only decides when to ask.
/// </para>
/// </summary>
public static class FlowShapePredictor
{
    /// <summary>Default recursion cap — an inbound method's routed site script is depth 1, a nested <c>Scripts.Call</c> depth 2.</summary>
    public const int DefaultMaxDepth = 4;

    /// <summary>Note attached to the request node when the script does not parse.</summary>
    public const string ParseErrorNote = "parse error";

    /// <summary>
    /// Predicts the flow of an inbound API method: an <see cref="FlowStepKind.InboundRequest"/>
    /// node first, the method script's calls, one hop into each routed site script the resolver
    /// can supply (recursively up to <paramref name="maxDepth"/>), and a
    /// <see cref="FlowStepKind.Response"/> node last.
    /// </summary>
    /// <param name="methodName">The inbound method name (titles the request node).</param>
    /// <param name="methodScript">The method's C# script body.</param>
    /// <param name="resolveRouteScript">
    /// <c>(instanceCode, scriptName)</c> → the site script body, or null when it cannot be
    /// resolved. Called with the literal instance code when the route target is a constant, and
    /// with the target expression's source text otherwise (so a resolver may still answer for a
    /// 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>
    public static PredictedFlow PredictInboundMethod(
        string methodName,
        string methodScript,
        Func<string, string, string?> resolveRouteScript,
        int maxDepth = DefaultMaxDepth)
    {
        ArgumentNullException.ThrowIfNull(resolveRouteScript);
        var b = new Builder(resolveRouteScript, Math.Max(1, maxDepth));
        var request = b.AddNode(FlowStepKind.InboundRequest, FlowLane.Central, $"POST /api/{methodName}", inputDependent: false, note: null);

        try
        {
            if (!b.Walk(methodScript ?? string.Empty, FlowLane.Central, instanceCode: null, depth: 0))
                b.Annotate(request, ParseErrorNote);
        }
        catch (Exception)
        {
            // A predictor must never take the page down; degrade to the request/response pair.
            b.Reset(keep: 1);
            b.Annotate(request, ParseErrorNote);
        }

        b.AddNode(FlowStepKind.Response, FlowLane.Central, "Response", inputDependent: false, note: null);
        return b.Build();
    }

    /// <summary>
    /// Predicts the flow of a site script run: a <see cref="FlowStepKind.ScriptRun"/> node first,
    /// then the script's attribute writes/waits and nested calls. Nested <c>Scripts.Call</c>
    /// targets are not expanded (no resolver) — they appear as unexpanded ScriptRun nodes.
    /// </summary>
    /// <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>
    public static PredictedFlow PredictSiteScript(string scriptName, string scriptBody, int maxDepth = DefaultMaxDepth)
    {
        var b = new Builder((_, _) => null, Math.Max(1, maxDepth));
        var root = b.AddNode(FlowStepKind.ScriptRun, FlowLane.Site, scriptName, inputDependent: false, note: null);

        try
        {
            if (!b.Walk(scriptBody ?? string.Empty, FlowLane.Site, instanceCode: null, depth: 1))
                b.Annotate(root, ParseErrorNote);
        }
        catch (Exception)
        {
            b.Reset(keep: 1);
            b.Annotate(root, ParseErrorNote);
        }

        return b.Build();
    }

    /// <summary>Accumulates nodes/edges and owns the chain ("previous node") state across nested walks.</summary>
    private sealed class Builder
    {
        private readonly Func<string, string, string?> _resolve;
        private readonly int _maxDepth;
        private readonly List<PredictedNode> _nodes = [];
        private readonly List<PredictedEdge> _edges = [];
        private string? _previous;
        private string? _pendingNote;

        internal Builder(Func<string, string, string?> resolve, int maxDepth)
        {
            _resolve = resolve;
            _maxDepth = maxDepth;
        }

        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.</summary>
        internal string AddNode(FlowStepKind kind, FlowLane lane, string title, bool inputDependent, string? note)
        {
            var id = "n" + (_nodes.Count + 1).ToString(CultureInfo.InvariantCulture);
            var mergedNote = note ?? _pendingNote;
            if (note != null && _pendingNote != null)
                mergedNote = $"{_pendingNote}; {note}";
            _pendingNote = null;

            _nodes.Add(new PredictedNode(id, kind, lane, title, inputDependent, mergedNote));
            if (_previous != null)
            {
                var fromLane = _nodes.First(n => n.Id == _previous).Lane;
                _edges.Add(new PredictedEdge(_previous, id, (fromLane == FlowLane.Central) != (lane == FlowLane.Central)));
            }

            _previous = id;
            return id;
        }

        internal void Annotate(string id, string note)
        {
            var i = _nodes.FindIndex(n => n.Id == id);
            if (i < 0) return;
            var n = _nodes[i];
            _nodes[i] = n with { Note = n.Note == null ? note : $"{n.Note}; {note}" };
        }

        /// <summary>Drops everything after the first <paramref name="keep"/> nodes (fault recovery).</summary>
        internal void Reset(int keep)
        {
            if (_nodes.Count > keep) _nodes.RemoveRange(keep, _nodes.Count - keep);
            var ids = _nodes.Select(n => n.Id).ToHashSet(StringComparer.Ordinal);
            _edges.RemoveAll(e => !ids.Contains(e.From) || !ids.Contains(e.To));
            _previous = _nodes.Count > 0 ? _nodes[^1].Id : null;
            _pendingNote = null;
        }

        /// <summary>
        /// Walks one script body in the given lane. Returns false when the body has parse
        /// errors (nothing is emitted for it), true otherwise.
        /// </summary>
        internal bool Walk(string code, FlowLane lane, string? instanceCode, int depth)
        {
            var tree = CSharpSyntaxTree.ParseText(code, new CSharpParseOptions(kind: SourceCodeKind.Script));
            if (tree.GetDiagnostics().Any(d => d.Severity == DiagnosticSeverity.Error))
                return false;

            new Walker(this, lane, instanceCode, depth).Visit(tree.GetRoot());
            _pendingNote = null; // a trailing guard with nothing after it has no node to annotate
            return true;
        }

        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>
        internal void ExpandScript(string instanceCode, string scriptName, int depth)
        {
            if (depth >= _maxDepth)
            {
                Annotate(_previous!, "depth limit reached; not expanded");
                return;
            }

            string? body;
            try
            {
                body = _resolve(instanceCode, scriptName);
            }
            catch (Exception)
            {
                body = null;
            }

            if (body == null)
                return;

            if (!Walk(body, FlowLane.Site, instanceCode, depth + 1))
                Annotate(_previous!, ParseErrorNote);
        }
    }

    /// <summary>Source-order visitor that turns recognised script-API calls into nodes.</summary>
    private sealed class Walker : CSharpSyntaxWalker
    {
        private readonly Builder _b;
        private readonly FlowLane _lane;
        private readonly string? _instanceCode;
        private readonly int _depth;

        internal Walker(Builder b, FlowLane lane, string? instanceCode, int depth)
        {
            _b = b;
            _lane = lane;
            _instanceCode = instanceCode;
            _depth = depth;
        }

        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>
        public override void VisitIfStatement(IfStatementSyntax node)
        {
            Visit(node.Condition);
            Visit(node.Statement);
            if (node.Else != null)
                Visit(node.Else);

            var returnsEarly = node.Statement.DescendantNodesAndSelf().OfType<ReturnStatementSyntax>().Any()
                || node.Statement.DescendantNodesAndSelf().OfType<ThrowStatementSyntax>().Any();
            if (returnsEarly)
                _b.QueueNote($"early return: {Condense(node.Condition.ToString())}");
        }

        public override void VisitAssignmentExpression(AssignmentExpressionSyntax node)
        {
            // recv.Attributes["X"] = v  /  Attributes["X"] = v
            if (node.Left is ElementAccessExpressionSyntax ea
                && Strip(ea.Expression.ToString()) is var recv
                && (recv == "Attributes" || recv.EndsWith(".Attributes", StringComparison.Ordinal)))
            {
                var (attr, dependent) = LiteralOrExpr(ea.ArgumentList.Arguments.FirstOrDefault()?.Expression);
                _b.AddNode(FlowStepKind.AttributeWrite, FlowLane.Tags, Qualify(attr), dependent, null);
            }

            base.VisitAssignmentExpression(node);
        }

        public override void VisitInvocationExpression(InvocationExpressionSyntax node)
        {
            // Visit inner invocations first? No — source order for a chained call like
            // Route.To(x).Call(y) is the outer call; the inner To(x) is part of its target.
            // Nested invocations inside ARGUMENTS are visited after this node is emitted,
            // which is the order they would produce trace rows only when they are awaited
            // first — acceptable for a shape preview.
            var handled = TryHandle(node);
            if (!handled)
                base.VisitInvocationExpression(node);
            else
                foreach (var arg in node.ArgumentList.Arguments)
                    Visit(arg.Expression);
        }

        private bool TryHandle(InvocationExpressionSyntax node)
        {
            if (node.Expression is not MemberAccessExpressionSyntax ma)
                return false;

            var member = ma.Name.Identifier.ValueText;
            var receiverText = Strip(ma.Expression.ToString());
            var args = node.ArgumentList.Arguments;

            // Route.To(<target>).Call(<script>, …) / .SetAttributes(…) / .WaitForAttribute(…)
            if (ma.Expression is InvocationExpressionSyntax inner
                && inner.Expression is MemberAccessExpressionSyntax innerMa
                && Strip(innerMa.ToString()) == "Route.To")
            {
                var (target, targetDependent) = LiteralOrExpr(inner.ArgumentList.Arguments.FirstOrDefault()?.Expression);
                switch (member)
                {
                    case "Call":
                    {
                        var (script, scriptDependent) = LiteralOrExpr(args.FirstOrDefault()?.Expression);
                        var title = targetDependent ? $"Route.To({target}).Call({script})" : $"{target}.{script}";
                        _b.AddNode(FlowStepKind.RouteCall, FlowLane.Central, title, targetDependent || scriptDependent,
                            targetDependent ? "route target is computed from inputs" : null);
                        if (!scriptDependent)
                        {
                            var runTitle = targetDependent ? script : $"{target}.{script}";
                            _b.AddNode(FlowStepKind.ScriptRun, FlowLane.Site, runTitle, targetDependent, null);
                            _b.ExpandScript(target, script, _depth);
                        }
                        return true;
                    }
                    case "SetAttributes":
                        _b.AddNode(FlowStepKind.AttributeWrite, FlowLane.Tags, $"{target}.SetAttributes", true, null);
                        return true;
                    case "WaitForAttribute":
                    {
                        var (attr, dependent) = LiteralOrExpr(args.FirstOrDefault()?.Expression);
                        _b.AddNode(FlowStepKind.AttributeWait, FlowLane.Site, $"{target}.{attr}", targetDependent || dependent, null);
                        return true;
                    }
                    default:
                        return false; // GetAttributes and friends are reads — no trace row, no node
                }
            }

            // Scripts.Call("Name", …) — a nested script run on the same instance.
            if (receiverText == "Scripts" && member == "Call")
            {
                var (script, dependent) = LiteralOrExpr(args.FirstOrDefault()?.Expression);
                _b.AddNode(FlowStepKind.ScriptRun, FlowLane.Site, Qualify(script), dependent, null);
                if (!dependent && _instanceCode != null)
                    _b.ExpandScript(_instanceCode, script, _depth);
                return true;
            }

            // ….Attributes.<op>(…)
            if (receiverText == "Attributes" || receiverText.EndsWith(".Attributes", StringComparison.Ordinal))
            {
                switch (member)
                {
                    case "WriteBatchAndWaitAsync":
                    {
                        // (batch, triggerAttr, triggerValue, waitAttr, waitValue, timeout)
                        var (trigger, triggerDependent) = LiteralOrExpr(args.ElementAtOrDefault(1)?.Expression);
                        var (wait, waitDependent) = LiteralOrExpr(args.ElementAtOrDefault(3)?.Expression);
                        _b.AddNode(FlowStepKind.AttributeWrite, FlowLane.Tags, Qualify($"batch + {trigger}"), triggerDependent, null);
                        _b.AddNode(FlowStepKind.AttributeWait, FlowLane.Site, Qualify(wait), waitDependent, null);
                        return true;
                    }
                    case "WaitAsync":
                    case "WaitForAsync":
                    {
                        var (attr, dependent) = LiteralOrExpr(args.FirstOrDefault()?.Expression);
                        _b.AddNode(FlowStepKind.AttributeWait, FlowLane.Site, Qualify(attr), dependent, null);
                        return true;
                    }
                    case "SetAsync":
                    {
                        var (attr, dependent) = LiteralOrExpr(args.FirstOrDefault()?.Expression);
                        _b.AddNode(FlowStepKind.AttributeWrite, FlowLane.Tags, Qualify(attr), dependent, null);
                        return true;
                    }
                    default:
                        return false;
                }
            }

            // ExternalSystem.Call / CachedCall, Database.*, Notify.Send — shown, never chained across.
            if (receiverText == "ExternalSystem" && member is "Call" or "CachedCall")
            {
                var (system, dependent) = LiteralOrExpr(args.FirstOrDefault()?.Expression);
                _b.AddNode(FlowStepKind.ApiCall, _lane, $"ExternalSystem.{member}({system})", dependent, null);
                return true;
            }

            if (receiverText == "Database")
            {
                var (conn, dependent) = LiteralOrExpr(args.FirstOrDefault()?.Expression);
                _b.AddNode(FlowStepKind.DbCall, _lane, $"Database.{member}({conn})", dependent, null);
                return true;
            }

            if (receiverText == "Notify" && member == "Send")
            {
                _b.AddNode(FlowStepKind.Notify, _lane, "Notify.Send", false, null);
                return true;
            }

            return false;
        }

        private string Qualify(string name)
            => _instanceCode == null ? name : $"{_instanceCode}.{name}";

        /// <summary>A string literal resolves to its value; anything else is input-dependent and shown as its source text.</summary>
        private static (string Text, bool Dependent) LiteralOrExpr(ExpressionSyntax? expr)
        {
            if (expr == null)
                return ("?", true);
            if (expr is LiteralExpressionSyntax lit && lit.IsKind(SyntaxKind.StringLiteralExpression))
                return (lit.Token.ValueText, false);
            return (Condense(expr.ToString()), true);
        }

        private static string Condense(string text)
        {
            var oneLine = string.Join(" ", text.Split(['\r', '\n'], StringSplitOptions.RemoveEmptyEntries).Select(l => l.Trim()));
            return oneLine.Length <= 80 ? oneLine : oneLine[..77] + "…";
        }
    }
}