using System.Globalization;
using Jellyfin.Plugin.JRay.Models;

namespace Jellyfin.Plugin.JRay.Services;

/// <summary>
/// The one place that decides whether a truth file speaks a version this plugin
/// understands.
/// </summary>
/// <remarks>
/// <b>Flag day, not dual-accept.</b> Only <see cref="SupportedVersion"/> is
/// accepted; every other value is refused on every path — sidecar read, managed
/// <c>PUT</c>, managed store load, and converted manifest. There is no
/// transitional v1 read path.
/// <para>
/// All three components are pre-release and move together, and the alternative
/// carries a cost that outlasts the transition: a v1 read path is the one nobody
/// exercises, so it is the one that rots, and it would have to be dragged
/// through every subsequent change to the reader.
/// </para>
/// <para>
/// <b>The consequence is stated rather than discovered:</b> v1 sidecar files
/// already on disk stop being read at the bump and stay dark until the library
/// is re-extracted. Callers log the rejection naming the file and the version
/// found, because an item that looks un-extracted when it is merely stale is the
/// failure mode that wastes a user's compute.
/// </para>
/// <para>
/// This exists as a shared unit because the check used to live only in the
/// <c>PUT</c> controller while sidecar reads did not check at all — so the
/// format the plugin claimed to require and the format it would actually parse
/// were different things.
/// </para>
/// </remarks>
// TRACES: JR-003 | SR-003
public static class TruthSchema
{
    /// <summary>
    /// The only <c>schema_version</c> this plugin reads or writes.
    /// </summary>
    /// <remarks>
    /// System-level (SR-003): the same number means the same format in all three
    /// repos, and is incremented once per breaking change across all of them.
    /// </remarks>
    public const int SupportedVersion = 2;

    /// <summary>
    /// Determines whether a truth file speaks the supported version.
    /// </summary>
    /// <param name="truth">The parsed truth file, which may be <c>null</c>.</param>
    /// <returns><c>true</c> only when the version matches exactly.</returns>
    public static bool IsSupported(TruthFile? truth)
        => truth is not null && truth.SchemaVersion == SupportedVersion;

    /// <summary>
    /// Builds the message describing why a truth file was refused.
    /// </summary>
    /// <remarks>
    /// Names both the version found and the version expected. A rejection that
    /// says only "unsupported" leaves the reader unable to tell a stale file
    /// from a corrupt one.
    /// </remarks>
    /// <param name="found">The version encountered.</param>
    /// <returns>A message naming both versions.</returns>
    public static string DescribeRejection(int found)
        => string.Create(
            CultureInfo.InvariantCulture,
            $"Unsupported schema_version {found}; expected {SupportedVersion}. Re-extract the item — v1 truth data is no longer read.");
}