using GitConverter.Lib.Models;

namespace GitConverter.Lib.Converters
{
    /// <summary>
    /// Contract for a single converter implementation that knows how to transform a GIS input
    /// artifact from one canonical format option to another.
    /// </summary>
    /// <remarks>
    /// <para>
    /// Implementations of <see cref="IConverter"/> encapsulate the conversion logic for a
    /// particular source/target format pair. The interface is intentionally small: callers
    /// provide input and output paths along with canonical format option strings and the
    /// converter returns a <see cref="ConversionResult"/> describing success or failure.
    /// </para>
    /// <para>
    /// Error handling and diagnostics:
    /// - Implementations should prefer returning <see cref="ConversionResult.Failure(string)"/>
    ///   for known failure conditions (invalid inputs, missing files, validation errors, converter
    ///   failures) rather than throwing exceptions. This keeps higher-level callers and tests
    ///   deterministic and allows clear user-facing messages.
    /// - Unexpected exceptions may still occur; converters should catch such exceptions where
    ///   appropriate, log diagnostic details, and return a failure result. Avoid letting
    ///   exceptions escape unless they represent truly unrecoverable framework-level failures.
    /// </para>
    /// <para>
    /// Concurrency and thread-safety:
    /// - The interface itself is stateless. Implementations should avoid relying on mutable
    ///   static state so multiple converter instances can be used concurrently by callers.
    /// - If implementations maintain shared resources (e.g., caches, static drivers), they must
    ///   manage synchronization internally.
    /// </para>
    /// <para>
    /// Side-effects and cleanup:
    /// - Implementations may create or modify the provided <paramref name="outputFolderPath"/>
    ///   and <paramref name="tempFolderPath"/>. Converters should document whether they create
    ///   or remove temporary files and folders. When possible prefer to clean up intermediate
    ///   artifacts created during successful conversions and leave the temp folder intact only
    ///   when it existed prior to the run.
    /// </para>
    /// <para>
    /// Runtime behavior in tests:
    /// - Tests in this repository invoke the ConsoleApp entry point via <c>Program.Run(string[])</c>
    ///   and expect converters to return a <see cref="ConversionResult"/> rather than calling
    ///   <c>Environment.Exit</c>. Implementations must therefore not terminate the process.
    /// </para>
    /// </remarks>
    public interface IConverter
    {
        /// <summary>
        /// Execute a conversion run.
        /// </summary>
        /// <param name="gisInputFilePath">Path to the input artifact. May be a single file or an archive.</param>
        /// <param name="gisSourceFormatOption">Canonical source format option (e.g. "Shapefile").</param>
        /// <param name="gisTargetFormatOption">Canonical target format option (e.g. "GeoJson").</param>
        /// <param name="outputFolderPath">Destination folder where output files should be written.</param>
        /// <param name="tempFolderPath">Temporary working folder for extraction and intermediates.</param>
        /// <returns>
        /// A <see cref="ConversionResult"/> describing success or failure. On success the result may
        /// include informational text such as produced file paths; on failure it should include a
        /// concise message suitable for user-facing diagnostics.
        /// </returns>
        /// <remarks>
        /// Implementations should validate inputs and return appropriate failure results for
        /// missing/invalid arguments. The method must not call <c>Environment.Exit</c> or terminate
        /// the process; it is expected to return a result so callers (including unit tests) can
        /// assert on the outcome. If the converter requires additional configuration or logging it
        /// should acquire those resources from the surrounding host rather than reaching into global
        /// state.
        /// </remarks>
        ConversionResult Convert(
            string gisInputFilePath,
            string gisSourceFormatOption,
            string gisTargetFormatOption,
            string outputFolderPath,
            string tempFolderPath);
    }
}