feat: add delete-impact endpoints

1mpossible-code · 1mpossible-code · commit f0854d4892dc · 2026-04-05T12:00:00.000-04:00
diff --git a/data/countries.py b/data/countries.py
@@ -255,13 +255,51 @@ def get_dependent_states_count(country_code: str) -> int:
     return len(states_list)
 
 
+def get_dependent_cities_count(country_code: str) -> int:
+    """
+    Check how many cities belong to this country.
+    """
+    import data.cities as cities
+
+    cities_list = cities.get_cities_by_country(country_code)
+    return len(cities_list)
+
+
+def get_country_delete_impact(country_code: str) -> dict | None:
+    """
+    Return dependency counts that would be affected by deleting a country.
+    Returns None when the country does not exist.
+    """
+    normalized_code = country_code.upper()
+    country = get_country_by_code(normalized_code)
+    if not country:
+        return None
+
+    states_count = get_dependent_states_count(normalized_code)
+    cities_count = get_dependent_cities_count(normalized_code)
+
+    return {
+        COUNTRY_CODE: normalized_code,
+        "exists": True,
+        "states": states_count,
+        "cities": cities_count,
+        "direct_dependency_count": states_count,
+        "total_dependency_count": states_count + cities_count,
+        "blocked": states_count > 0,
+    }
+
+
 def can_delete_country(country_code: str) -> tuple[bool, str]:
     """
     Check if country can be safely deleted.
     Returns (can_delete: bool, reason: str)
     """
-    dependent_count = get_dependent_states_count(country_code)
-    if dependent_count > 0:
+    delete_impact = get_country_delete_impact(country_code)
+    if delete_impact is None:
+        return True, ""
+
+    dependent_count = delete_impact["states"]
+    if delete_impact["blocked"]:
         return (
             False,
             f"Cannot delete: {dependent_count} state(s) depend on this country",
diff --git a/data/states.py b/data/states.py
@@ -207,13 +207,37 @@ def get_dependent_cities_count(state_code: str) -> int:
     return len(cities_list)
 
 
+def get_state_delete_impact(state_code: str) -> dict | None:
+    """
+    Return dependency counts for deleting a state.
+    """
+    normalized_code = state_code.upper()
+    state = get_state_by_code(normalized_code)
+    if not state:
+        return None
+
+    cities_count = get_dependent_cities_count(normalized_code)
+    return {
+        STATE_CODE: normalized_code,
+        "exists": True,
+        "cities": cities_count,
+        "direct_dependency_count": cities_count,
+        "total_dependency_count": cities_count,
+        "blocked": cities_count > 0,
+    }
+
+
 def can_delete_state(state_code: str) -> tuple[bool, str]:
     """
     Check if state can be safely deleted.
     Returns (can_delete: bool, reason: str)
     """
-    dependent_count = get_dependent_cities_count(state_code)
-    if dependent_count > 0:
+    delete_impact = get_state_delete_impact(state_code)
+    if delete_impact is None:
+        return True, ""
+
+    dependent_count = delete_impact["cities"]
+    if delete_impact["blocked"]:
         return False, f"Cannot delete: {dependent_count} city/cities depend on this state"
     return True, ""
 
diff --git a/data/tests/test_countries.py b/data/tests/test_countries.py
@@ -192,24 +192,73 @@ def test_delete_country_not_found(self):
 
     def test_delete_country_with_dependent_states(self):
         """Test that deleting a country with states raises ValueError."""
-        with patch('data.countries.get_dependent_states_count', return_value=5):
+        with patch('data.countries.can_delete_country', return_value=(False, "Cannot delete: 5 state(s) depend on this country")):
             with pytest.raises(ValueError, match="Cannot delete: 5 state"):
                 countries.delete_country('US')
 
     def test_can_delete_country_with_dependencies(self):
         """Test can_delete_country returns False when states exist."""
-        with patch('data.countries.get_dependent_states_count', return_value=3):
+        with patch('data.countries.get_country_delete_impact', return_value={
+            countries.COUNTRY_CODE: 'US',
+            'exists': True,
+            'states': 3,
+            'cities': 8,
+            'direct_dependency_count': 3,
+            'total_dependency_count': 11,
+            'blocked': True,
+        }):
             can_delete, reason = countries.can_delete_country('US')
             assert can_delete is False
             assert "3 state" in reason
 
     def test_can_delete_country_no_dependencies(self):
         """Test can_delete_country returns True when no states exist."""
-        with patch('data.countries.get_dependent_states_count', return_value=0):
+        with patch('data.countries.get_dependent_states_count', return_value=0), \
+             patch('data.countries.get_dependent_cities_count', return_value=0), \
+             patch('data.countries.get_country_by_code', return_value=countries.TEST_COUNTRY):
             can_delete, reason = countries.can_delete_country('XX')
             assert can_delete is True
             assert reason == ""
 
+    def test_get_country_delete_impact_zero_dependencies(self):
+        """Delete impact reports zero totals when no dependent states or cities exist."""
+        with patch('data.countries.get_country_by_code', return_value=countries.TEST_COUNTRY), \
+             patch('data.countries.get_dependent_states_count', return_value=0), \
+             patch('data.countries.get_dependent_cities_count', return_value=0):
+            impact = countries.get_country_delete_impact('us')
+
+            assert impact == {
+                countries.COUNTRY_CODE: 'US',
+                'exists': True,
+                'states': 0,
+                'cities': 0,
+                'direct_dependency_count': 0,
+                'total_dependency_count': 0,
+                'blocked': False,
+            }
+
+    def test_get_country_delete_impact_includes_total_cities(self):
+        """Delete impact total counts include both direct states and nested cities."""
+        with patch('data.countries.get_country_by_code', return_value=countries.TEST_COUNTRY), \
+             patch('data.countries.get_dependent_states_count', return_value=2), \
+             patch('data.countries.get_dependent_cities_count', return_value=7):
+            impact = countries.get_country_delete_impact('us')
+
+            assert impact == {
+                countries.COUNTRY_CODE: 'US',
+                'exists': True,
+                'states': 2,
+                'cities': 7,
+                'direct_dependency_count': 2,
+                'total_dependency_count': 9,
+                'blocked': True,
+            }
+
+    def test_get_country_delete_impact_not_found(self):
+        """Delete impact returns None when the country does not exist."""
+        with patch('data.countries.get_country_by_code', return_value=None):
+            assert countries.get_country_delete_impact('xx') is None
+
     def test_country_exists_true(self):
         """Test checking if a country exists - returns True."""
         with patch('data.countries.get_country_by_code') as mock_get:
diff --git a/data/tests/test_states.py b/data/tests/test_states.py
@@ -282,19 +282,68 @@ def test_delete_state_with_dependent_cities(self):
             mock_can_delete.assert_called_once_with("NY")
 
     def test_can_delete_state_with_dependencies(self):
-        """Test can_delete_state returns False when cities exist."""
-        with patch("data.states.get_dependent_cities_count", return_value=5):
+        """Test can_delete_state returns False when delete impact is blocked."""
+        with patch(
+            "data.states.get_state_delete_impact",
+            return_value={
+                S.STATE_CODE: "NY",
+                "exists": True,
+                "cities": 5,
+                "direct_dependency_count": 5,
+                "total_dependency_count": 5,
+                "blocked": True,
+            },
+        ):
             can_delete, reason = S.can_delete_state("NY")
             assert can_delete is False
             assert "5 city" in reason
 
     def test_can_delete_state_no_dependencies(self):
         """Test can_delete_state returns True when no cities exist."""
-        with patch("data.states.get_dependent_cities_count", return_value=0):
+        with patch("data.states.get_dependent_cities_count", return_value=0), patch(
+            "data.states.get_state_by_code", return_value=S.TEST_STATE
+        ):
             can_delete, reason = S.can_delete_state("XX")
             assert can_delete is True
             assert reason == ""
 
+    def test_get_state_delete_impact_zero_dependencies(self):
+        """Delete impact reports zero totals when no dependent cities exist."""
+        with patch("data.states.get_state_by_code", return_value=S.TEST_STATE), patch(
+            "data.states.get_dependent_cities_count", return_value=0
+        ):
+            impact = S.get_state_delete_impact("ny")
+
+            assert impact == {
+                S.STATE_CODE: "NY",
+                "exists": True,
+                "cities": 0,
+                "direct_dependency_count": 0,
+                "total_dependency_count": 0,
+                "blocked": False,
+            }
+
+    def test_get_state_delete_impact_with_dependencies(self):
+        """Delete impact reports dependency counts and blocking when cities exist."""
+        with patch("data.states.get_state_by_code", return_value=S.TEST_STATE), patch(
+            "data.states.get_dependent_cities_count", return_value=3
+        ):
+            impact = S.get_state_delete_impact("ny")
+
+            assert impact == {
+                S.STATE_CODE: "NY",
+                "exists": True,
+                "cities": 3,
+                "direct_dependency_count": 3,
+                "total_dependency_count": 3,
+                "blocked": True,
+            }
+
+    def test_get_state_delete_impact_not_found(self):
+        """Delete impact returns None when the state does not exist."""
+        with patch("data.states.get_state_by_code", return_value=None):
+            assert S.get_state_delete_impact("zz") is None
+
     # ===== Existence check tests =====
 
     def test_state_exists(self):
diff --git a/server/countries_endpoints.py b/server/countries_endpoints.py
@@ -218,6 +218,41 @@ def add_country_links(country: dict) -> dict:
     },
 )
 
+delete_impact_model = countries_ns.model(
+    "CountryDeleteImpact",
+    {
+        "country_code": fields.String(
+            required=True, description="ISO 3166-1 alpha-2 country code", example="US"
+        ),
+        "exists": fields.Boolean(
+            required=True,
+            description="Whether the requested country exists",
+            example=True,
+        ),
+        "states": fields.Integer(
+            required=True, description="Number of directly dependent states", example=5
+        ),
+        "cities": fields.Integer(
+            required=True, description="Number of cascade-affected cities", example=120
+        ),
+        "direct_dependency_count": fields.Integer(
+            required=True,
+            description="Total number of directly dependent records that block a non-cascade delete",
+            example=5,
+        ),
+        "total_dependency_count": fields.Integer(
+            required=True,
+            description="Total number of dependent records affected by cascade delete",
+            example=125,
+        ),
+        "blocked": fields.Boolean(
+            required=True,
+            description="Whether safe delete is blocked by direct dependencies",
+            example=True,
+        ),
+    },
+)
+
 list_parser = reqparse.RequestParser()
 list_parser.add_argument(
     "limit",
@@ -341,6 +376,35 @@ def get(self, country_code):
             )
 
 
+@countries_ns.route("/<string:country_code>/delete-impact")
+@countries_ns.param("country_code", "The country code (ISO 3166-1 alpha-2)")
+class CountryDeleteImpact(Resource):
+    """Country delete impact endpoint"""
+
+    @countries_ns.doc("get_country_delete_impact")
+    @countries_ns.marshal_with(delete_impact_model)
+    @countries_ns.response(HTTPStatus.NOT_FOUND, "Country not found", error_model)
+    def get(self, country_code):
+        """
+        Retrieve dependency counts for deleting a country.
+        Returns counts the UI can use before confirming delete.
+        """
+        try:
+            impact = countries_data.get_country_delete_impact(country_code.upper())
+        except Exception as e:
+            countries_ns.abort(
+                HTTPStatus.INTERNAL_SERVER_ERROR, f"Database error: {str(e)}"
+            )
+
+        if impact:
+            return impact, HTTPStatus.OK
+
+        countries_ns.abort(
+            HTTPStatus.NOT_FOUND,
+            f"Country with code '{country_code}' not found",
+        )
+
+
 @countries_ns.route("/<string:country_code>")
 @countries_ns.param("country_code", "The country code (ISO 3166-1 alpha-2)")
 class Country(Resource):
diff --git a/server/states_endpoints.py b/server/states_endpoints.py
@@ -112,6 +112,38 @@
     },
 )
 
+delete_impact_model = states_ns.model(
+    "StateDeleteImpact",
+    {
+        "state_code": fields.String(
+            required=True, description="State code (e.g., CA, NY)", example="CA"
+        ),
+        "exists": fields.Boolean(
+            required=True,
+            description="Whether the requested state exists",
+            example=True,
+        ),
+        "cities": fields.Integer(
+            required=True, description="Number of directly dependent cities", example=12
+        ),
+        "direct_dependency_count": fields.Integer(
+            required=True,
+            description="Total number of directly dependent records that block a non-cascade delete",
+            example=12,
+        ),
+        "total_dependency_count": fields.Integer(
+            required=True,
+            description="Total number of dependent records affected by cascade delete",
+            example=12,
+        ),
+        "blocked": fields.Boolean(
+            required=True,
+            description="Whether safe delete is blocked by direct dependencies",
+            example=True,
+        ),
+    },
+)
+
 # Parser for query parameters on the GET /states endpoint
 list_parser = reqparse.RequestParser()
 list_parser.add_argument(
@@ -241,6 +273,34 @@ def post(self):
             )
 
 
+@states_ns.route("/<string:state_code>/delete-impact")
+@states_ns.param("state_code", "The state code (e.g., CA, NY)")
+class StateDeleteImpact(Resource):
+    """State delete impact endpoint"""
+
+    @states_ns.doc("get_state_delete_impact")
+    @states_ns.marshal_with(delete_impact_model)
+    @states_ns.response(HTTPStatus.NOT_FOUND, "State not found", error_model)
+    def get(self, state_code: str):
+        """
+        Retrieve dependency counts for deleting a state.
+        Returns counts the UI can use before confirming delete.
+        """
+        try:
+            impact = states_data.get_state_delete_impact(state_code.upper())
+        except Exception as e:
+            states_ns.abort(
+                HTTPStatus.INTERNAL_SERVER_ERROR, f"Database error: {str(e)}"
+            )
+
+        if impact:
+            return impact, HTTPStatus.OK
+
+        states_ns.abort(
+            HTTPStatus.NOT_FOUND, f"State with code '{state_code}' not found"
+        )
+
+
 @states_ns.route("/<string:state_code>")
 @states_ns.param("state_code", "The state code (e.g., CA, NY)")
 class State(Resource):
diff --git a/server/tests/test_countries_endpoints.py b/server/tests/test_countries_endpoints.py
diff --git a/server/tests/test_states_endpoints.py b/server/tests/test_states_endpoints.py
