using Aspose.Gis;
using GisConverter.Lib.Logging;
using GisConverter.Lib.Models;
using System;

namespace GisConverter.Lib.Converters
{
    /// <summary>
    /// Universal converter implementation that orchestrates a conversion run using Aspose.GIS drivers.
    /// </summary>
    /// <remarks>
    /// <para>
    /// Overview
    /// - <c>UniversalGisConverter</c> is the orchestrator used by hosts (ConsoleApp, services) and by tests to perform
    ///   format conversions using driver implementations (commonly Aspose.GIS-backed drivers). It centralizes the
    ///   "non-driver" responsibilities so individual converters can remain focused on driver-specific mapping and
    ///   option construction.
    /// </para>
    ///
    /// <para>
    /// Responsibilities
    /// - Validate inputs and early-fail with friendly diagnostics using <see cref="ConverterUtils.ValidateInputs"/>.
    /// - Prepare filesystem locations (output and temp) with <see cref="ConverterUtils.PreparePaths"/>.
    /// - Handle archives and multi-file sources via <see cref="ConverterUtils.PrepareSourceFile"/>, preserving the supplied
    ///   temp-folder contract and attempting best-effort cleanup when this instance performed extraction.
    /// - Resolve source and destination drivers by mapping canonical option keys to driver instances
    ///   via <see cref="ConverterUtils.ConversionOptionToDriver"/>.
    /// - Construct driver-specific conversion options via <see cref="ConverterUtils.BuildConversionOptions"/>
    ///   and derive deterministic output paths via <see cref="ConverterUtils.BuildOutputPath"/>.
    /// - Invoke the underlying driver conversion call (<c>VectorLayer.Convert</c>) and translate driver outcomes into
    ///   stable <see cref="ConversionResult"/> values for callers and tests.
    /// </para>
    ///
    /// <para>
    /// Logging and diagnostics
    /// - This orchestrator emits structured, level-appropriate log tokens to facilitate automated assertions in tests:
    ///   - Debug: parameter traces, detailed cleanup internals and low-level diagnostics.
    ///   - Info: start/finish markers and high-level success messages with output paths.
    ///   - Warn: non-fatal issues (cleanup failures, fallbacks).
    ///   - Error: validation failures, mapping errors and unexpected exceptions (exception objects are logged).
    /// - Tests and maintainers should assert on stable tokens (case-insensitive substrings) rather than entire messages.
    /// </para>
    ///
    /// <para>
    /// Error handling and return contract
    /// - The <see cref="Convert(string,string,string,string,string)"/> method surfaces errors via returned
    ///   <see cref="ConversionResult"/> instances. Known/expected problems (validation, mapping, missing archive components)
    ///   return <c>ConversionResult.Failure(...)</c> with user-friendly messages suitable for display or CI assertions.
    /// - Unexpected exceptions are caught at the orchestrator boundary, logged at Error level (with exception details) and
    ///   converted to a failure result. The method is designed not to throw for recoverable errors so callers and tests
    ///   remain deterministic.
    /// </para>
    ///
    /// <para>
    /// Concurrency and side-effects
    /// - The class contains no shared mutable state and is safe to construct/invoke concurrently. Converters must avoid
    ///   relying on mutable static state so multiple instances can safely operate in parallel test runners or hosting services.
    /// - Side-effects are limited to creating/modifying files under the supplied <paramref name="outputFolderPath"/> and
    ///   <paramref name="tempFolderPath"/>. When extraction is performed the method attempts best-effort cleanup of temp
    ///   content it created; it will not remove a caller-managed temp folder unless it performed the extraction into it.
    /// </para>
    ///
    /// <para>
    /// Test guidance
    /// - Unit tests
    ///   - Drive early-failure branches by supplying invalid inputs, missing archive components or invalid mapping keys.
    ///   - Inject a test <c>TestLogger</c> and assert on log tokens (Debug/Info/Warn/Error) with <c>LogAssert</c>.
    ///   - Use injected factories or fakes to avoid invoking heavy drivers for unit-level coverage.
    /// - Integration tests
    ///   - Gate driver-backed integration tests with environment flags (for example <c>GISCONVERTER_ENABLE_INTEGRATION=1</c>)
    ///     and license checks (for example <c>AsposeLicenseManager.ApplyLicense()</c>).
    ///   - Keep sample artifacts small and place them under <c>TestsApp/TestData/&lt;format&gt;</c> with copy-to-output set.
    /// - Assertions
    ///   - Prefer checking <see cref="ConversionResult.Status"/>, file existence under the output folder, and case-insensitive
    ///     substring checks of <see cref="ConversionResult.Message"/> and logs. Avoid brittle exact message equality.
    /// </para>
    ///
    /// <para>
    /// Security and IO considerations
    /// - Treat untrusted inputs conservatively. Use <see cref="ConverterUtils"/> helpers that implement zip-slip guards and
    ///   bounded reads when inspecting archive contents. Do not write files outside the intended temp or output folders.
    /// - Sanitize temporary names and limit resource creation to avoid denial-of-service risks on shared CI agents.
    /// </para>
    ///
    /// <para>
    /// Extension points and best practices for implementers
    /// - Keep orchestration separate from driver specifics: let <c>ConverterUtils</c> and driver-specific option builders
    ///   hold mapping logic so orchestration remains simple and testable.
    /// - If the orchestrator requires additional configuration or logging, prefer constructor injection of dependencies
    ///   rather than using global/static state to improve testability.
    /// - Document whether temp folders are removed on success. Tests sometimes assert on temp-folder cleanup, so be explicit.
    /// </para>
    ///
    /// <para>
    /// Example usage
    /// <code>
    /// var conv = new UniversalGisConverter();
    /// var result = conv.Convert("input.geojson", "GeoJson", "Shapefile", "out", "temp");
    /// if (result.IsSuccess) Console.WriteLine($"Wrote outputs to: {result.Message}");
    /// else Console.Error.WriteLine($"Conversion failed: {result.Message}");
    /// </code>
    /// </para>
    /// </remarks>
    public class UniversalGisConverter : IConverter
    {
        /// <summary>
        /// Execute a conversion run from a source GIS artifact to a target format.
        /// </summary>
        /// <param name="gisInputFilePath">Path to the GIS input (file or archive).</param>
        /// <param name="gisSourceFormatOption">Canonical source format option (for example "Shapefile", "GeoJson").</param>
        /// <param name="gisTargetFormatOption">Canonical target format option (for example "GeoJson", "Kml").</param>
        /// <param name="outputFolderPath">Destination folder for output files. The method will create the folder if needed.</param>
        /// <param name="tempFolderPath">Temporary folder for archive extraction and intermediate files. When the method
        /// performs extraction it will attempt best-effort cleanup of this folder; if the caller supplied an already-existing
        /// temp folder that should be preserved, pass a distinct path.</param>
        /// <returns>
        /// A <see cref="ConversionResult"/> indicating success or failure. On success the result's <see cref="ConversionResult.Message"/>
        /// contains a brief summary including the resolved output path. On failure the message contains a concise diagnostic
        /// token suitable for logs and CI assertion.
        /// </returns>
        /// <remarks>
        /// <para>
        /// High-level algorithm
        /// 1. Log a debug-level parameter trace and an info-level "starting conversion" marker.
        /// 2. Validate inputs with <see cref="ConverterUtils.ValidateInputs"/>. Validation failures return early
        ///    with a failure <see cref="ConversionResult"/> that contains a user-friendly message.
        /// 3. Ensure output / temp folders exist using <see cref="ConverterUtils.PreparePaths"/>. Fail early for
        ///    irrecoverable path errors.
        /// 4. Prepare the source file. If the source is an archive, <see cref="ConverterUtils.PrepareSourceFile"/>
        ///    will extract components into the supplied temp folder and return the extracted source path plus a
        ///    flag indicating extraction occurred. If preparation fails the method returns the failure result.
        /// 5. Resolve Aspose drivers for the source and target formats via
        ///    <see cref="ConverterUtils.ConversionOptionToDriver"/>. If a mapping cannot be resolved return a failure.
        /// 6. Build the driver-specific options via <see cref="ConverterUtils.BuildConversionOptions"/> and compute
        ///    the output path via <see cref="ConverterUtils.BuildOutputPath"/>.
        /// 7. Call <c>VectorLayer.Convert</c> with the resolved drivers and options. On success log Info and return
        ///    <see cref="ConversionResult.Success(string)"/>; on unexpected exceptions catch, log and return Failure.
        /// 8. In a finally block attempt to cleanup the temp folder only when this method performed extraction into it.
        /// </para>
        /// </remarks>
        public ConversionResult Convert(
            string gisInputFilePath,
            string gisSourceFormatOption,
            string gisTargetFormatOption,
            string outputFolderPath,
            string tempFolderPath)
        {
            // Parameter trace for diagnostics
            Log.Debug($"UniversalGisConverter.Convert params: gisInputFilePath='{gisInputFilePath}', gisSourceFormatOption='{gisSourceFormatOption}', gisTargetFormatOption='{gisTargetFormatOption}',outputFolderPath='{outputFolderPath}', tempFolderPath='{tempFolderPath}'"); Log.Info($"CsvConverter: starting conversion (option='{gisTargetFormatOption}', input='{gisInputFilePath}').");

            Log.Info($"UniversalGisConverter: starting conversion (option='{gisTargetFormatOption}', input='{gisInputFilePath}').");


            // Step 1: Validate inputs
            var validation = ConverterUtils.ValidateInputs(gisInputFilePath, outputFolderPath, tempFolderPath);
            if (validation != null) return validation;

            // Step 2: Prepare directories
            var preparation = ConverterUtils.PreparePaths(outputFolderPath, tempFolderPath);
            if (preparation != null) return preparation;

            bool extractedToTemp = false;

            try
            {
                // Step 3: Handle archive extraction or single file
                var (sourcePath, wasExtracted, results) = ConverterUtils.PrepareSourceFile(
                    gisInputFilePath,
                    gisSourceFormatOption,
                    tempFolderPath);
                if (results == null)
                {
                    return results;
                }
                extractedToTemp = wasExtracted;

                // Step 4: Resolve drivers
                var srcDriver = ConverterUtils.ConversionOptionToDriver(gisSourceFormatOption) as FileDriver;
                var destDriver = ConverterUtils.ConversionOptionToDriver(gisTargetFormatOption) as FileDriver;

                if (srcDriver == null || destDriver == null)
                {
                    if (srcDriver == null)
                    {
                        Log.Error($"Conversion failed: invalid source format option '{gisSourceFormatOption}'");
                    }
                    if (destDriver == null)
                    {
                        Log.Error($"Conversion failed: invalid destination format option '{gisTargetFormatOption}'");
                    }
                    return ConversionResult.Failure("Invalid source or destination format");
                }

                // Step 5: Build output path
                var outputPath = ConverterUtils.BuildOutputPath(outputFolderPath, gisTargetFormatOption);

                // Step 6: Build format-specific options
                var options = ConverterUtils.BuildConversionOptions(gisSourceFormatOption, gisTargetFormatOption);

                // Step 7: Perform conversion
                VectorLayer.Convert(sourcePath, srcDriver, outputPath, destDriver, options);
                Log.Info($"Conversion succeeded: {outputPath}");
                return ConversionResult.Success($"Converted to {gisTargetFormatOption}; output: {outputPath}");
            }
            catch (Exception ex)
            {
                Log.Error($"Conversion failed: {ex.Message}", ex);
                return ConversionResult.Failure($"Unexpected error: {ex.Message}");
            }
            finally
            {
                Log.Info("Starting conversion attempt.");

                // Only cleanup when we actually extracted files into the temp folder
                // This avoids removing a pre-existing temp folder that may be managed by the caller.
                if (extractedToTemp)
                {
                    Log.Debug("Cleaning up temp folder.");
                    try
                    {
                        ConverterUtils.TryCleanupTempFolder(tempFolderPath);
                    }
                    catch (Exception ex)
                    {
                        Log.Debug($"Cleanup failed: {ex.Message}");
                    }
                }
                Log.Info("Finished conversion attempt.");
            }
        }

    }
}