using GitConverter.Lib.Models;

namespace GitConverter.Lib.Converters
{
    /// <summary>
    /// Minimal converter contract used by the library.
    /// Implementations convert a GIS input artifact (single file or archive) into an output folder path (the output file in output folder path created by the system in runtime).
    /// In addition use internally temp folder path.
    /// and return a <see cref="ConversionResult"/> describing success/failure and an optional human-friendly message.
    /// </summary>
    /// <remarks>
    /// - Implementations should be lightweight and testable. Prefer dependency injection for heavy dependencies.
    /// - The <see cref="Convert"/> method must not throw for expected/known error conditions; instead return a
    ///   <see cref="ConversionResult"/> with a failure status. Only unexpected exceptions should propagate.
    /// - Signature change: converters now receive the resolved GIS conversion option as the second parameter.
    ///   This allows a single converter implementation to support multiple option aliases or to receive the
    ///   canonical option used to resolve it (for logging, heuristics or sub-mode selection).
    /// - The <c>tempFolderPath</c> parameter provides a location for temporary or intermediate files
    ///   (for example: extraction of archives, intermediate staging or working files). Converters should:
    ///     - Create the directory if it does not exist.
    ///     - Use the provided path when available; if null or empty, return failure with a proper message.
    ///     - Attempt to clean up intermediate files on successful completion; leaving files on failure may help diagnostics.
    ///     - Never assume external cleanup unless explicitly documented.
    /// - If an implementation allocates unmanaged resources or needs deterministic cleanup, implement <see cref="System.IDisposable"/>
    ///   and document ownership/lifetime expectations.
    /// - Converters may be constructed per-call (stateless) or reused; document any thread-safety requirements on the concrete type.
    /// - Prefer returning informative <see cref="ConversionResult.Message"/> values so CLI callers can print actionable messages.
    /// </remarks>
    public interface IConverter
    {
        /// <summary>
        /// Convert the given GIS input (file or archive) and write outputs to <paramref name="outFolderPath"/>.
        /// </summary>
        /// <param name="gisInputFilePath">
        /// Path to the GIS input artifact. May be a single file (e.g., .geojson, .shp) or an archive containing
        /// multiple files required by the format. Implementations should validate input existence and format.
        /// </param>
        /// <param name="gisTargetFormatOption">
        /// The canonical format option string used to select this converter (for example "EsriJson", "Shapefile").
        /// Provides the converter context and allows converters to implement alias-aware behavior.
        /// </param>
        /// <param name="outputFolderPath">
        /// Path to the destination output path(the output file in output folder path created by the system in runtime).
        /// </param>
        /// <param name="tempFolderPath">
        /// Path to a temporary working folder the converter may use for extraction or intermediate files.
        /// If null or empty converters should return a Failure result with a proper message. Converters should create
        /// the folder when required and attempt to remove intermediate files on successful completion; document any deviations.
        /// </param>
        /// <returns>
        /// A <see cref="ConversionResult"/> indicating success or failure and containing a human-friendly message.
        /// On success implementations may include brief diagnostics in <see cref="ConversionResult.Message"/>.
        /// </returns>
        /// <remarks>
        /// - Implementations should aim for clear, actionable <see cref="ConversionResult.Message"/> values to help CLI users.
        /// - If the converter writes large outputs or performs long-running work consider reporting progress outside of this API.
        /// - Avoid throwing for expected validation or conversion errors; return Failure results instead. Unexpected exceptions
        ///   may propagate and should be documented by the implementation.
        /// </remarks>
        ConversionResult Convert(string gisInputFilePath, string gisTargetFormatOption, string outputFolderPath, string tempFolderPath);
    }
}