namespace GitConverter.Lib.Models
{
    /// <summary>
    /// Canonical file-type identifiers used by converters and tests.
    /// </summary>
    /// <remarks>
    /// Purpose
    /// - Provide a compact, stable set of logical identifiers for common GIS/vector file formats
    ///   used across the library (converters, orchestration, tests and READMEs).
    ///
    /// How to use
    /// - Map user-facing converter option keys (for example "Csv", "GeoJson", "Shapefile")
    ///   to this enum via <see cref="FileExtensionHelpers.FromOption(string)"/> when composing
    ///   deterministic output file names or test expectations.
    /// - Obtain the canonical dot-prefixed suffix using <see cref="FileExtension.ToDotExtension"/>.
    ///   Example:
    ///     var fe = FileExtensionHelpers.FromOption("Csv");
    ///     var ext = fe.HasValue ? fe.Value.ToDotExtension() : FileExtension.Csv.ToDotExtension();
    ///     var outFile = Path.Combine(outputFolder, $"output_{timestamp}{ext}");
    ///
    /// Rationale
    /// - Centralizing extension decisions avoids scattered literal strings (".csv", ".shp", ".json")
    ///   and reduces the chance of inconsistencies across converters and tests.
    /// - Enum values represent logical formats (drivers) rather than file system details; the
    ///   mapping to a physical suffix is defined by the helpers.
    ///
    /// Stability and evolution
    /// - Additions to this enum are backwards compatible for callers that use the enum by name.
    /// - If you must change a canonical suffix (for example change FileGdb from ".gdbtable"
    ///   to ".gdb"), change only the mapping in the helpers and update tests accordingly.
    ///
    /// Note on FileGdb
    /// - The project currently maps FileGdb to ".gdbtable" per repository convention. Change
    ///   that mapping in FileExtensionHelpers if you prefer the more common ".gdb".
    ///
    /// Thread-safety
    /// - The enum is a pure value type and safe for concurrent use.
    /// </remarks>
    public enum FileExtension
    {
        Csv,
        EsriJson,
        FileGdb,
        GeoJson,
        GeoJsonSeq,
        GeoPackage,
        Gml,
        Gpx,
        Kml,
        Kmz,
        MapInfoInterchange,
        MapInfoTab,
        OsmXml,
        Shapefile,
        TopoJson
    }
}