using System.Collections.Generic;
using GitConverter.Lib.Converters;

namespace GitConverter.Lib.Factories
{
    /// <summary>
    /// Produces <see cref="IConverter"/> instances for a given conversion option string.
    /// </summary>
    /// <remarks>
    /// <para>
    /// The <c>IConverterFactory</c> interface abstracts the creation of converter instances based
    /// on human-friendly format option strings (for example, "Shapefile", "GeoJson", "Csv").
    /// Implementations map canonical display keys to concrete <see cref="IConverter"/> factories
    /// and provide both throwing and non-throwing creation patterns to suit different callers.
    /// </para>
    /// <para>
    /// Design guidance
    /// - Use <see cref="TryCreate(string,out IConverter)"/> for CLI flows, interactive tooling and tests
    ///   where callers prefer to handle unsupported options without exceptions.
    /// - Use <see cref="Create(string)"/> when the caller expects a converter and prefers an exception
    ///   to be thrown for unsupported options (the implementation may include friendly suggestions
    ///   in the thrown <see cref="KeyNotFoundException"/> message).
    /// </para>
    /// <para>
    /// Thread-safety and lifetime
    /// - Factory implementations are typically constructed once (during application startup) and used
    ///   as a read-only registry thereafter. Implementations should document whether they are safe for
    ///   concurrent use; recommended implementations avoid mutable shared state and are safe for
    ///   concurrent Create/TryCreate calls.
    /// </para>
    /// <para>
    /// Error handling
    /// - <see cref="TryCreate(string,out IConverter)"/> must return <c>false</c> when the requested option
    ///   cannot be resolved. Implementations may log diagnostic context but should not throw from this
    ///   method for unsupported options. If a factory delegate throws during instantiation it is recommended
    ///   that the implementation catch the exception, log it, set the out parameter to <c>null</c> and return <c>false</c>.
    /// - <see cref="Create(string)"/> may throw <see cref="KeyNotFoundException"/> when the option is unsupported.
    ///   Implementations may include a helpful suggestion in the exception message (for example: "Did you mean 'GeoJson'?").
    /// </para>
    /// <para>
    /// Testing guidance
    /// - For unit tests prefer providing a test-specific factory implementation or a factory constructed
    ///   with a small registrations map to avoid instantiating heavy dependencies. Assert behavior of both
    ///   <see cref="Create(string)"/> and <see cref="TryCreate(string,out IConverter)"/> as appropriate.
    /// </para>
    /// <para>
    /// Example
    /// <code>
    /// IConverterFactory factory = new ConverterFactory();
    /// if (factory.TryCreate("Shapefile", out var converter))
    /// {
    ///     var result = converter.Convert(...);
    /// }
    /// else
    /// {
    ///     Console.WriteLine("Unsupported converter option. Supported: " + string.Join(", ", factory.GetSupportedOptions()));
    /// }
    /// </code>
    /// </remarks>
    public interface IConverterFactory
    {
        /// <summary>
        /// Create a converter for the given option or throw if unsupported.
        /// </summary>
        /// <param name="formatOption">User-provided option (case/format tolerant).</param>
        /// <returns>An instance of <see cref="IConverter"/> configured for the requested option.</returns>
        /// <remarks>
        /// Implementations should validate <paramref name="formatOption"/> and throw a
        /// <see cref="KeyNotFoundException"/> when the option is unsupported. Exception messages
        /// may include friendly suggestions to improve CLI UX. Use this method when the caller
        /// prefers an exception for control flow rather than handling a boolean result.
        /// </remarks>
        IConverter Create(string formatOption);

        /// <summary>
        /// Try to create a converter for the given option. Returns false if unsupported.
        /// </summary>
        /// <param name="formatOption">User-provided option string.</param>
        /// <param name="converter">When true returned, the resolved converter instance; otherwise, <c>null</c>.</param>
        /// <returns>True when a converter was created; false otherwise.</returns>
        /// <remarks>
        /// This non-throwing alternative is suitable for CLI parsing and tests where callers want
        /// to present usage information or suggestions rather than handle exceptions. Implementations
        /// should catch instantiation exceptions from underlying factory delegates, log diagnostic
        /// details and return <c>false</c>.
        /// </remarks>
        bool TryCreate(string formatOption, out IConverter converter);

        /// <summary>
        /// Returns the supported option keys (human-friendly).
        /// </summary>
        /// <returns>An ordered, read-only collection of display keys suitable for help text.</returns>
        /// <remarks>
        /// The returned collection is intended for presentation to users (for example, help/usage
        /// messages) and should contain stable, human-friendly display keys rather than internal
        /// normalized keys.
        /// </remarks>
        IReadOnlyCollection<string> GetSupportedOptions();
    }
}