Preserve Microsoft enum compatibility

Root cause: adding fallback enum members and parser hardening without locking the public numeric surface left compatibility and review gaps in the Microsoft provider package.

Restore stable EntityType numeric values, make Azure result filtering explicit, and add a regression snapshot so future enum drift is caught in tests.

Author: niemyjski

src/Geocoding.Microsoft/AzureMapsGeocoder.cs

@@ -1,4 +1,5 @@
 using System.Globalization;
+using System.Linq;
 using System.Net;
 using System.Net.Http;
 using System.Text.Json;
@@ -224,13 +225,11 @@ private IEnumerable<AzureMapsAddress> ParseResponse(AzureSearchResponse response
     {
         if (response.Results is not null && response.Results.Length > 0)
         {
-            foreach (var result in response.Results)
+            foreach (var result in response.Results.Where(result => result?.Position is not null))
             {
-                if (result?.Position is null)
-                    continue;
-
-                var address = result.Address ?? new AzureAddressPayload();
-                var formattedAddress = FirstNonEmpty(address.FreeformAddress, address.StreetNameAndNumber, BuildStreetLine(address.StreetNumber, address.StreetName), result.Poi?.Name, result.Type, FirstNonEmpty(address.LocalName, address.Municipality, address.CountryTertiarySubdivision), address.Country);
+                var azureResult = result!;
+                var address = azureResult.Address ?? new AzureAddressPayload();
+                var formattedAddress = FirstNonEmpty(address.FreeformAddress, address.StreetNameAndNumber, BuildStreetLine(address.StreetNumber, address.StreetName), azureResult.Poi?.Name, azureResult.Type, FirstNonEmpty(address.LocalName, address.Municipality, address.CountryTertiarySubdivision), address.Country);
                 if (String.IsNullOrWhiteSpace(formattedAddress))
                     continue;
 
@@ -241,16 +240,16 @@ private IEnumerable<AzureMapsAddress> ParseResponse(AzureSearchResponse response
 
                 yield return new AzureMapsAddress(
                     formattedAddress,
-                    new Location(result.Position.Lat, result.Position.Lon),
+                    new Location(azureResult.Position!.Lat, azureResult.Position.Lon),
                     BuildStreetLine(address.StreetNumber, address.StreetName),
                     FirstNonEmpty(address.CountrySubdivisionName, address.CountrySubdivision),
                     address.CountrySecondarySubdivision,
                     address.Country,
                     locality,
                     neighborhood,
                     address.PostalCode,
-                    EvaluateEntityType(result),
-                    EvaluateConfidence(result));
+                    EvaluateEntityType(azureResult),
+                    EvaluateConfidence(azureResult));
             }
             yield break;
         }

src/Geocoding.Microsoft/EntityType.cs

@@ -9,9 +9,9 @@
 public enum EntityType
 {
     /// <summary>Unknown entity type not recognized by the library.</summary>
-    Unknown,
+    Unknown = -1,
     /// <summary>The Address value.</summary>
-    Address,
+    Address = 0,
     /// <summary>The AdminDivision1 value.</summary>
     AdminDivision1,
     /// <summary>The AdminDivision2 value.</summary>

test/Geocoding.Tests/MicrosoftJsonCompatibilityTest.cs

@@ -1,11 +1,222 @@
 using System.Text.Json;
+using Geocoding.Microsoft;
 using Geocoding.Microsoft.Json;
 using Xunit;
 
 namespace Geocoding.Tests;
 
 public class MicrosoftJsonCompatibilityTest
 {
+  [Fact]
+  public void EntityType_PreservesExistingNumericValues()
+  {
+    string[] expectedNames = """
+    Unknown
+    Address
+    AdminDivision1
+    AdminDivision2
+    AdminDivision3
+    AdministrativeBuilding
+    AdministrativeDivision
+    AgriculturalStructure
+    Airport
+    AirportRunway
+    AmusementPark
+    AncientSite
+    Aquarium
+    Archipelago
+    Autorail
+    Basin
+    Battlefield
+    Bay
+    Beach
+    BorderPost
+    Bridge
+    BusinessCategory
+    BusinessCenter
+    BusinessName
+    BusinessStructure
+    BusStation
+    Camp
+    Canal
+    Cave
+    CelestialFeature
+    Cemetery
+    Census1
+    Census2
+    CensusDistrict
+    Channel
+    Church
+    CityHall
+    Cliff
+    ClimateRegion
+    Coast
+    CommunityCenter
+    Continent
+    ConventionCenter
+    CountryRegion
+    Courthouse
+    Crater
+    CulturalRegion
+    Current
+    Dam
+    Delta
+    Dependent
+    Desert
+    DisputedArea
+    DrainageBasin
+    Dune
+    EarthquakeEpicenter
+    Ecoregion
+    EducationalStructure
+    ElevationZone
+    Factory
+    FerryRoute
+    FerryTerminal
+    FishHatchery
+    Forest
+    FormerAdministrativeDivision
+    FormerPoliticalUnit
+    FormerSovereign
+    Fort
+    Garden
+    GeodeticFeature
+    GeoEntity
+    GeographicPole
+    Geyser
+    Glacier
+    GolfCourse
+    GovernmentStructure
+    Heliport
+    Hemisphere
+    HigherEducationFacility
+    HistoricalSite
+    Hospital
+    HotSpring
+    Ice
+    IndigenousPeoplesReserve
+    IndustrialStructure
+    InformationCenter
+    InternationalDateline
+    InternationalOrganization
+    Island
+    Isthmus
+    Junction
+    Lake
+    LandArea
+    Landform
+    LandmarkBuilding
+    LatitudeLine
+    Library
+    Lighthouse
+    LinguisticRegion
+    LongitudeLine
+    MagneticPole
+    Marina
+    Market
+    MedicalStructure
+    MetroStation
+    MilitaryBase
+    Mine
+    Mission
+    Monument
+    Mosque
+    Mountain
+    MountainRange
+    Museum
+    NauticalStructure
+    NavigationalStructure
+    Neighborhood
+    Oasis
+    ObservationPoint
+    Ocean
+    OfficeBuilding
+    Park
+    ParkAndRide
+    Pass
+    Peninsula
+    Plain
+    Planet
+    Plate
+    Plateau
+    PlayingField
+    Pole
+    PoliceStation
+    PoliticalUnit
+    PopulatedPlace
+    Postcode
+    Postcode1
+    Postcode2
+    Postcode3
+    Postcode4
+    PostOffice
+    PowerStation
+    Prison
+    Promontory
+    RaceTrack
+    Railway
+    RailwayStation
+    RecreationalStructure
+    Reef
+    Region
+    ReligiousRegion
+    ReligiousStructure
+    ResearchStructure
+    Reserve
+    ResidentialStructure
+    RestArea
+    River
+    Road
+    RoadBlock
+    RoadIntersection
+    Ruin
+    Satellite
+    School
+    ScientificResearchBase
+    Sea
+    SeaplaneLandingArea
+    ShipWreck
+    ShoppingCenter
+    Shrine
+    Site
+    SkiArea
+    Sovereign
+    SpotElevation
+    Spring
+    Stadium
+    StatisticalDistrict
+    Structure
+    TectonicBoundary
+    TectonicFeature
+    Temple
+    TimeZone
+    TouristStructure
+    Trail
+    TransportationStructure
+    Tunnel
+    UnderwaterFeature
+    UrbanRegion
+    Valley
+    Volcano
+    Wall
+    Waterfall
+    WaterFeature
+    Well
+    Wetland
+    Zoo
+    PointOfInterest
+    """.Split('\n', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+
+    Assert.Equal(expectedNames.Length, Enum.GetNames<EntityType>().Length);
+
+    for (int index = 0; index < expectedNames.Length; index++)
+    {
+      var entityType = Enum.Parse<EntityType>(expectedNames[index]);
+      var expectedValue = index == 0 ? -1 : index - 1;
+      Assert.Equal(expectedValue, (int)entityType);
+    }
+  }
+
     [Fact]
     public void Response_WithLocationResource_DeserializesToLocation()
     {