namespace ZB.MOM.WW.OtOpcUa.Core.Abstractions;

/// <summary>
///     The one worst-of-input rule every derived-value seam uses — scripted alarms, virtual tags and
///     the Calculation driver.
///
///     <para><b>The contract it implements</b> (archreview R3-02, "the stale-Good family"): a value
///     consumer never reports a quality better than its source's. A node derived from driver values
///     carries, at worst, the worst status among its inputs — a Bad input makes the derived node Bad
///     with that input's sub-code, an Uncertain input makes it Uncertain, and a source that has
///     stopped communicating is a Bad input for everything downstream of it.</para>
///
///     <para><b>Why it lives here.</b> Core.Abstractions is the one assembly all three seams already
///     reference (Commons, Runtime and the driver assemblies all sit above it), and
///     <see cref="DataValueSnapshot"/> — the shape the rule reads — is declared beside it. Stating
///     the rule three times is how the three seams drifted apart in the first place.</para>
///
///     <para><b>Severity, not equality.</b> Comparison is on the OPC UA Part 4 severity bits (the top
///     two: <c>00</c> Good, <c>01</c> Uncertain, <c>10</c>/<c>11</c> Bad); the sub-code below them is
///     carried through verbatim because the sub-code is the diagnostic
///     (<c>BadNoCommunication</c> = go look at the device, <c>BadWaitingForInitialData</c> = it never
///     arrived, <c>BadInternalError</c> = the script).</para>
/// </summary>
public static class InputQuality
{
    /// <summary>
    ///     No value has ever been received for this input — the status a fresh node is materialised
    ///     with, and what <see cref="WorstOf"/> reports for a dependency slot that holds no snapshot
    ///     at all. Spelled here rather than taken from <c>Commons.OpcUa.OpcUaStatus</c> because
    ///     Core.Abstractions sits <em>below</em> Commons and deliberately references nothing.
    /// </summary>
    public const uint BadWaitingForInitialData = 0x80320000u;

    /// <summary>
    ///     The worst status among <paramref name="inputs"/>: the highest Part 4 severity, carrying
    ///     that input's own sub-code. A <see langword="null"/> entry is a dependency that has never
    ///     been pushed and reports <see cref="BadWaitingForInitialData"/> — reporting Good for it is
    ///     the laundering this helper exists to stop. An empty set is Good: there is nothing to be
    ///     worse than.
    /// </summary>
    /// <param name="inputs">The dependency snapshots, in a stable order.</param>
    /// <returns>The worst status code observed.</returns>
    /// <remarks>
    ///     Among <em>equal</em> severity the first entry seen wins, so a re-evaluation over the same
    ///     inputs reports the same sub-code instead of oscillating between two equally-bad codes.
    /// </remarks>
    public static uint WorstOf(IEnumerable<DataValueSnapshot?> inputs)
    {
        ArgumentNullException.ThrowIfNull(inputs);

        var worst = 0u;
        var worstSeverity = 0u;
        foreach (var input in inputs)
        {
            var status = input?.StatusCode ?? BadWaitingForInitialData;
            var severity = status >> 30;
            if (severity <= worstSeverity) continue;
            worstSeverity = severity;
            worst = status;
        }

        return worst;
    }

    /// <summary>
    ///     True when a consumer may evaluate against a value carrying <paramref name="statusCode"/>.
    ///     Good and Uncertain are usable — an Uncertain value is present and a script can make a
    ///     qualified decision from it; Bad is not, and a consumer holds instead (the alarm engine's
    ///     long-standing policy, generalised).
    /// </summary>
    /// <param name="statusCode">The status code to classify.</param>
    /// <returns><see langword="true"/> for Good or Uncertain severity.</returns>
    public static bool IsUsable(uint statusCode) => (statusCode >> 30) < 2;
}