namespace ZB.MOM.WW.OtOpcUa.Commons.OpcUa;

/// <summary>
///     The handful of OPC UA status codes the engine layer needs to spell, plus the Part 4 severity
///     classification helpers that replaced the retired <c>OpcUaQuality</c> 3-state enum (Gitea #519).
///
///     <para><b>Why these are bare <c>uint</c> literals.</b> Commons and Runtime deliberately do not
///     reference the OPC UA SDK — <see cref="IOpcUaAddressSpaceSink"/> exists precisely so the Runtime
///     project can publish values without dragging in <c>Opc.Ua.Server</c>. That is the same layering
///     decision the driver assemblies make, and it carries the same single failure mode: nothing checks
///     the literal against the name. <c>StatusCodeParityTests</c> closes it by reflection, and it can
///     only see a <b>named</b> constant — so add codes here rather than writing a literal at a call
///     site, exactly as Gitea #497 concluded for the drivers.</para>
///
///     <para><b>Severity, not equality, is what callers should branch on.</b> A status code's top two
///     bits carry its Part 4 severity (00 = Good, 01 = Uncertain, 10/11 = Bad); everything below is the
///     sub-code. Before #519 the engine collapsed every value onto a 3-state enum here and the node
///     manager re-expanded <c>Bad</c> to a bare <c>0x80000000</c>, so no driver's sub-code ever reached
///     a client. The sub-code now rides through to the SDK verbatim, and any code that only needs the
///     bucket uses <see cref="IsGood"/> / <see cref="IsUncertain"/> / <see cref="IsBad"/> rather than
///     comparing against <see cref="Good"/> or <see cref="Bad"/>.</para>
/// </summary>
public static class OpcUaStatus
{
    /// <summary>The value is good. Part 4 severity <c>00</c>; the whole code is zero.</summary>
    public const uint Good = 0x00000000;

    /// <summary>Generic uncertain. Prefer a specific <c>Uncertain*</c> sub-code where one applies.</summary>
    public const uint Uncertain = 0x40000000;

    /// <summary>Generic bad, carrying no diagnostic beyond the severity. This is the value the retired
    /// 3-state projection produced for <em>every</em> bad status; a caller that has something more
    /// specific should say so instead.</summary>
    public const uint Bad = 0x80000000;

    /// <summary>No value has been received from the device yet. Written at materialisation and on every
    /// address-space reset, so a freshly-deployed or just-rebuilt node reads as "not yet polled" rather
    /// than as a device fault.</summary>
    public const uint BadWaitingForInitialData = 0x80320000;

    /// <summary>Communication with the source has been lost. The driver-connectivity annotation for a
    /// native alarm condition, and the sentinel several drivers map an explicit "unavailable" reading to.</summary>
    public const uint BadNoCommunication = 0x80310000;

    /// <summary>An internal failure produced no usable value — the virtual-tag path's code for a script
    /// that threw or timed out.</summary>
    public const uint BadInternalError = 0x80020000;

    /// <summary>Part 4 severity bucket of <paramref name="statusCode"/>: the top two bits.</summary>
    /// <param name="statusCode">The status code to classify.</param>
    /// <returns>0 for Good, 1 for Uncertain, 2 or 3 for Bad.</returns>
    public static uint Severity(uint statusCode) => statusCode >> 30;

    /// <summary>True when <paramref name="statusCode"/> is in the Good severity bucket.</summary>
    /// <param name="statusCode">The status code to classify.</param>
    /// <returns><see langword="true"/> when the value is usable.</returns>
    public static bool IsGood(uint statusCode) => Severity(statusCode) == 0;

    /// <summary>True when <paramref name="statusCode"/> is in the Uncertain severity bucket.</summary>
    /// <param name="statusCode">The status code to classify.</param>
    /// <returns><see langword="true"/> when the value is questionable but present.</returns>
    public static bool IsUncertain(uint statusCode) => Severity(statusCode) == 1;

    /// <summary>True when <paramref name="statusCode"/> is in the Bad severity bucket.</summary>
    /// <param name="statusCode">The status code to classify.</param>
    /// <returns><see langword="true"/> when the value must not be trusted.</returns>
    public static bool IsBad(uint statusCode) => Severity(statusCode) >= 2;
}