using System;

namespace GisConverter.Lib.Models
{
    /// <summary>
    /// Represents the outcome of a conversion operation.
    /// </summary>
    /// <remarks>
    /// <para>
    /// <see cref="ConversionResult"/> is an immutable value object intended to be returned by converter
    /// implementations and propagated between layers (for example from the conversion library back to
    /// the CLI). It contains:
    /// </para>
    /// <list type="bullet">
    ///   <item><description><see cref="Status"/> — the logical result code (Success/Failure).</description></item>
    ///   <item><description><see cref="Message"/> — a short, human-friendly message suitable for logs and CLI output.</description></item>
    ///   <item><description><see cref="TimestampUtc"/> — creation time in UTC for diagnostics and ordering.</description></item>
    /// </list>
    ///
    /// <para>
    /// Construction
    /// - Use the factory helpers <see cref="Success(string)"/> and <see cref="Failure(string)"/> to create
    ///   instances. These helpers normalize the message and set the timestamp consistently.
    /// </para>
    ///
    /// <para>
    /// Immutability & thread-safety
    /// - Instances are immutable after construction and therefore safe to share between threads.
    /// - The type exposes no mutating members.
    /// </para>
    ///
    /// <para>
    /// Equality semantics
    /// - Implements <see cref="IEquatable{ConversionResult}"/> to compare logical results.
    /// - Equality is based on <see cref="Status"/> and <see cref="Message"/> using ordinal comparison.
    /// - <see cref="TimestampUtc"/> is intentionally excluded from equality because it is diagnostic
    ///   metadata (creation time) rather than part of the logical outcome.
    /// - If a caller needs timestamp-aware equality, implement a custom comparer or wrap this type
    ///   rather than changing global semantics.
    /// </para>
    ///
    /// <para>
    /// Usage guidance
    /// - Return <see cref="Success(string)"/> from converters when the operation completed and produced
    ///   expected outputs. Keep messages concise (tests often assert on substrings).
    /// - Return <see cref="Failure(string)"/> for failures; include clear diagnostic tokens suitable for logs
    ///   and CI debugging. Avoid exposing secrets in messages.
    /// </para>
    /// </remarks>
    public sealed class ConversionResult : IEquatable<ConversionResult>
    {
        /// <summary>
        /// The status of the conversion.
        /// </summary>
        public ConversionStatus Status { get; }

        /// <summary>
        /// Human-friendly message describing the result. Empty string when not provided.
        /// Use this to surface concise diagnostics to CLI users or logs.
        /// </summary>
        /// <remarks>
        /// Keep messages brief and stable; tests and automation often match on case-insensitive
        /// substrings rather than exact full-text matches. Avoid embedding environment-specific
        /// paths or transient identifiers unless necessary.
        /// </remarks>
        public string Message { get; }

        /// <summary>
        /// UTC timestamp when the result instance was created.
        /// </summary>
        /// <remarks>
        /// This value is intended for diagnostics (correlation, ordering) and is not considered
        /// in logical equality. For deterministic tests avoid asserting on this value or provide
        /// a test seam that controls timestamps.
        /// </remarks>
        public DateTime TimestampUtc { get; }

        /// <summary>
        /// True when the conversion succeeded (<see cref="Status"/> is <see cref="ConversionStatus.Success"/>).
        /// </summary>
        public bool IsSuccess => Status == ConversionStatus.Success;

        private ConversionResult(ConversionStatus status, string message)
        {
            Status = status;
            Message = message ?? string.Empty;
            TimestampUtc = DateTime.UtcNow;
        }

        /// <summary>
        /// Create a success result with an optional message.
        /// </summary>
        /// <param name="message">Optional human-friendly message; null is treated as empty.</param>
        /// <returns>A new <see cref="ConversionResult"/> with <see cref="Status"/> == <see cref="ConversionStatus.Success"/>.</returns>
        /// <remarks>
        /// Use this factory from converters and hosts to represent successful conversions.
        /// Example: <c>return ConversionResult.Success("Wrote 3 files");</c>
        /// </remarks>
        public static ConversionResult? Success(string? message = null) =>
            new ConversionResult(ConversionStatus.Success, message ?? string.Empty);

        /// <summary>
        /// Create a failure result with an optional message describing the error.
        /// </summary>
        /// <param name="message">Optional error message; null is treated as empty.</param>
        /// <returns>A new <see cref="ConversionResult"/> with <see cref="Status"/> == <see cref="ConversionStatus.Failure"/>.</returns>
        /// <remarks>
        /// Provide concise diagnostic text suitable for logs and CI failure analysis. Prefer stable
        /// tokens that tests and automation can match against.
        /// Example: <c>return ConversionResult.Failure("Input archive missing .shp file");</c>
        /// </remarks>
        public static ConversionResult? Failure(string? message = null) =>
            new ConversionResult(ConversionStatus.Failure, message ?? string.Empty);

        /// <summary>
        /// Returns a compact textual representation useful for logs.
        /// </summary>
        /// <returns>String in the form "{Status}: {Message}".</returns>
        public override string ToString() => $"{Status}: {Message}";

        /// <summary>
        /// Strongly-typed equality comparing logical result values.
        /// - Compares <see cref="Status"/> and <see cref="Message"/> (ordinal).
        /// - Does not consider <see cref="TimestampUtc"/> in equality.
        /// </summary>
        /// <param name="other">Other <see cref="ConversionResult"/> to compare with.</param>
        /// <returns><c>true</c> when logically equal; otherwise <c>false</c>.</returns>
        public bool Equals(ConversionResult? other)
        {
            if (ReferenceEquals(null, other)) return false;
            if (ReferenceEquals(this, other)) return true;
            return Status == other.Status && string.Equals(Message, other.Message, StringComparison.Ordinal);
        }

        /// <summary>
        /// Object equality override delegates to strongly-typed equality.
        /// </summary>
        public override bool Equals(object? obj) => obj is ConversionResult other && Equals(other);

        /// <summary>
        /// Hash code based on the logical equality components.
        /// </summary>
        /// <remarks>
        /// Combines <see cref="Status"/> and <see cref="Message"/> (ordinal) into the hash. The timestamp is
        /// intentionally excluded so logically-equal results share the same hash code.
        /// </remarks>
        public override int GetHashCode()
        {
            unchecked
            {
                // combine Status and Message (ordinal) into hash
                int hash = 17;
                hash = hash * 31 + Status.GetHashCode();
                hash = hash * 31 + (Message != null ? StringComparer.Ordinal.GetHashCode(Message) : 0);
                return hash;
            }
        }

        /// <summary>
        /// Equality operator uses the same semantics as <see cref="Equals(ConversionResult)"/>.
        /// </summary>
        public static bool operator ==(ConversionResult? left, ConversionResult? right)
        {
            if (ReferenceEquals(left, right)) return true;
            if (ReferenceEquals(left, null)) return false;
            return left.Equals(right);
        }

        /// <summary>
        /// Inequality operator.
        /// </summary>
        public static bool operator !=(ConversionResult? left, ConversionResult? right) => !(left == right);
    }

    /// <summary>
    /// Status codes for <see cref="ConversionResult"/>.
    /// </summary>
    public enum ConversionStatus
    {
        /// <summary>Conversion completed successfully.</summary>
        Success = 0,
        /// <summary>Conversion failed (see <see cref="ConversionResult.Message"/> for details).</summary>
        Failure = 1
    }
}