feat: add @remove migration (#1151)

Closes #1144.

### Summary of Changes

- Migration of `@remove` annotations through a mapping from old api
elements to new api elements.
If the mapped apiv2 element is removable (a class or function), change
the target of the annotation.
Otherwise, mark the api element that are not removable with an `@todo`
annotation.
- New methods `get_annotated_api_element` and
`get_annotated_api_element_by_type` to get the element from an
annotation by its id.

### Testing Instructions

run the migrate command or view and run the `test_migration.py` file

Co-authored-by: Aclrian <Aclrian@users.noreply.github.com>

Author: Aclrian

package-parser/package_parser/processing/migration/_migrate.py

@@ -15,6 +15,9 @@
 from package_parser.processing.migration.annotations._migrate_move_annotation import (
     migrate_move_annotation,
 )
+from package_parser.processing.migration.annotations._migrate_remove_annotation import (
+    migrate_remove_annotation,
+)
 from package_parser.processing.migration.model import Mapping
 
 
@@ -60,6 +63,12 @@ def migrate_annotations(
             for annotation in migrate_rename_annotation(rename_annotation, mapping):
                 migrated_annotation_store.add_annotation(annotation)
 
+    for remove_annotation in annotationsv1.removeAnnotations:
+        mapping = _get_mapping_from_annotation(remove_annotation, mappings)
+        if mapping is not None:
+            for annotation in migrate_remove_annotation(remove_annotation, mapping):
+                migrated_annotation_store.add_annotation(annotation)
+
     for todo_annotation in annotationsv1.todoAnnotations:
         mapping = _get_mapping_from_annotation(todo_annotation, mappings)
         if mapping is not None:

package-parser/package_parser/processing/migration/annotations/_get_annotated_api_element.py

@@ -0,0 +1,36 @@
+from typing import List, Optional, TypeVar, Union
+
+from package_parser.processing.annotations.model import AbstractAnnotation
+from package_parser.processing.api.model import (
+    Attribute,
+    Class,
+    Function,
+    Parameter,
+    Result,
+)
+
+API_ELEMENTS = TypeVar("API_ELEMENTS", Class, Function, Parameter)
+
+
+def get_annotated_api_element(
+    annotation: AbstractAnnotation,
+    api_element_list: List[Union[Attribute, Class, Function, Parameter, Result]],
+) -> Optional[Union[Class, Function, Parameter]]:
+    for element in api_element_list:
+        if (
+            isinstance(element, (Class, Function, Parameter))
+            and element.id == annotation.target
+        ):
+            return element
+    return None
+
+
+def get_annotated_api_element_by_type(
+    annotation: AbstractAnnotation,
+    api_element_list: List[Union[Attribute, Class, Function, Parameter, Result]],
+    api_type: type[API_ELEMENTS],
+) -> Optional[API_ELEMENTS]:
+    for element in api_element_list:
+        if isinstance(element, api_type) and element.id == annotation.target:
+            return element
+    return None

package-parser/package_parser/processing/migration/annotations/_migrate_move_annotation.py

@@ -20,6 +20,7 @@
 )
 
 from ._constants import migration_author
+from ._get_annotated_api_element import get_annotated_api_element
 from ._get_migration_text import get_migration_text
 
 
@@ -61,15 +62,9 @@ def migrate_move_annotation(
         move_annotation.target = element.id
         return [move_annotation]
 
-    annotated_apiv1_element = None
-    for element in mapping.get_apiv1_elements():
-        if (
-            not isinstance(element, (Attribute, Result))
-            and move_annotation.target == element.id
-        ):
-            annotated_apiv1_element = element
-            break
-
+    annotated_apiv1_element = get_annotated_api_element(
+        move_annotation, mapping.get_apiv1_elements()
+    )
     if annotated_apiv1_element is None:
         return []
 

package-parser/package_parser/processing/migration/annotations/_migrate_remove_annotation.py

@@ -0,0 +1,91 @@
+from copy import deepcopy
+
+from package_parser.processing.annotations.model import (
+    AbstractAnnotation,
+    EnumReviewResult,
+    RemoveAnnotation,
+    TodoAnnotation,
+)
+from package_parser.processing.api.model import (
+    Attribute,
+    Class,
+    Function,
+    Parameter,
+    Result,
+)
+from package_parser.processing.migration.model import (
+    ManyToOneMapping,
+    Mapping,
+    OneToOneMapping,
+)
+
+from ._constants import migration_author
+from ._get_annotated_api_element import get_annotated_api_element
+from ._get_migration_text import get_migration_text
+
+
+def is_removeable(element: Attribute | Class | Function | Parameter | Result) -> bool:
+    return isinstance(element, (Class, Function))
+
+
+def migrate_remove_annotation(
+    remove_annotation: RemoveAnnotation, mapping: Mapping
+) -> list[AbstractAnnotation]:
+    remove_annotation = deepcopy(remove_annotation)
+    authors = remove_annotation.authors
+    authors.append(migration_author)
+    remove_annotation.authors = authors
+    migrate_text = get_migration_text(remove_annotation, mapping)
+
+    if isinstance(mapping, (ManyToOneMapping, OneToOneMapping)):
+        element = mapping.get_apiv2_elements()[0]
+        if isinstance(element, (Attribute, Result)):
+            return []
+        if not is_removeable(element):
+            return [
+                TodoAnnotation(
+                    element.id,
+                    authors,
+                    remove_annotation.reviewers,
+                    remove_annotation.comment,
+                    EnumReviewResult.NONE,
+                    migrate_text,
+                )
+            ]
+        remove_annotation.target = element.id
+        return [remove_annotation]
+
+    annotated_apiv1_element = get_annotated_api_element(
+        remove_annotation, mapping.get_apiv1_elements()
+    )
+    if annotated_apiv1_element is None:
+        return []
+
+    remove_annotations: list[AbstractAnnotation] = []
+    for element in mapping.get_apiv2_elements():
+        if (
+            isinstance(element, type(annotated_apiv1_element))
+            and is_removeable(element)
+            and not isinstance(element, (Attribute, Result))
+        ):
+            remove_annotations.append(
+                RemoveAnnotation(
+                    element.id,
+                    authors,
+                    remove_annotation.reviewers,
+                    remove_annotation.comment,
+                    EnumReviewResult.NONE,
+                )
+            )
+        elif not isinstance(element, (Attribute, Result)):
+            remove_annotations.append(
+                TodoAnnotation(
+                    element.id,
+                    authors,
+                    remove_annotation.reviewers,
+                    remove_annotation.comment,
+                    EnumReviewResult.NONE,
+                    migrate_text,
+                )
+            )
+    return remove_annotations

package-parser/package_parser/processing/migration/annotations/_migrate_todo_annotation.py

@@ -13,6 +13,7 @@
 )
 
 from ._constants import migration_author
+from ._get_annotated_api_element import get_annotated_api_element
 from ._get_migration_text import get_migration_text
 
 
@@ -34,15 +35,9 @@ def migrate_todo_annotation(
 
     migrate_text = get_migration_text(todo_annotation, mapping)
 
-    annotated_apiv1_element = None
-    for element in mapping.get_apiv1_elements():
-        if (
-            not isinstance(element, (Attribute, Result))
-            and todo_annotation.target == element.id
-        ):
-            annotated_apiv1_element = element
-            break
-
+    annotated_apiv1_element = get_annotated_api_element(
+        todo_annotation, mapping.get_apiv1_elements()
+    )
     if annotated_apiv1_element is None:
         return []
 

package-parser/package_parser/processing/migration/annotations/_migrate_value_annotation.py

@@ -1,5 +1,5 @@
 from copy import deepcopy
-from typing import Optional, Tuple, TypeVar
+from typing import Optional, Tuple
 
 from package_parser.processing.annotations.model import (
     AbstractAnnotation,
@@ -14,8 +14,6 @@
 from package_parser.processing.api.model import (
     AbstractType,
     Attribute,
-    Class,
-    Function,
     NamedType,
     Parameter,
     Result,
@@ -30,6 +28,7 @@
 )
 
 from ._constants import migration_author
+from ._get_annotated_api_element import get_annotated_api_element_by_type
 from ._get_migration_text import get_migration_text
 
 
@@ -254,26 +253,6 @@ def _have_same_value(
     return None
 
 
-API_ELEMENTS = TypeVar("API_ELEMENTS", Class, Function, Parameter)
-
-
-def get_api_element_from_mapping(
-    annotation: AbstractAnnotation, mapping: Mapping, api_type: type[API_ELEMENTS]
-) -> Optional[API_ELEMENTS]:
-    element_list = [
-        element
-        for element in mapping.get_apiv1_elements()
-        if (
-            isinstance(element, api_type)
-            and hasattr(element, "id")
-            and element.id == annotation.target
-        )
-    ]
-    if len(element_list) != 1:
-        return None
-    return element_list[0]
-
-
 def migrate_constant_annotation(
     constant_annotation: ConstantAnnotation, parameterv2: Parameter, mapping: Mapping
 ) -> Optional[ConstantAnnotation]:
@@ -291,7 +270,9 @@ def migrate_constant_annotation(
             constant_annotation.defaultValue,
         )
 
-    parameterv1 = get_api_element_from_mapping(constant_annotation, mapping, Parameter)
+    parameterv1 = get_annotated_api_element_by_type(
+        constant_annotation, mapping.get_apiv1_elements(), Parameter
+    )
     if parameterv1 is None:
         return None
     if _have_same_type(
@@ -312,7 +293,9 @@ def migrate_constant_annotation(
 def migrate_omitted_annotation(
     omitted_annotation: OmittedAnnotation, parameterv2: Parameter, mapping: Mapping
 ) -> Optional[OmittedAnnotation]:
-    parameterv1 = get_api_element_from_mapping(omitted_annotation, mapping, Parameter)
+    parameterv1 = get_annotated_api_element_by_type(
+        omitted_annotation, mapping.get_apiv1_elements(), Parameter
+    )
     if parameterv1 is None:
         return None
     type_and_same_value = _have_same_value(parameterv1, parameterv2)
@@ -346,7 +329,9 @@ def migrate_omitted_annotation(
 def migrate_optional_annotation(
     optional_annotation: OptionalAnnotation, parameterv2: Parameter, mapping: Mapping
 ) -> Optional[OptionalAnnotation]:
-    parameterv1 = get_api_element_from_mapping(optional_annotation, mapping, Parameter)
+    parameterv1 = get_annotated_api_element_by_type(
+        optional_annotation, mapping.get_apiv1_elements(), Parameter
+    )
     if parameterv1 is None:
         return None
     if parameterv2.type is not None and _have_same_type(
@@ -380,7 +365,9 @@ def migrate_optional_annotation(
 def migrate_required_annotation(
     required_annotation: RequiredAnnotation, parameterv2: Parameter, mapping: Mapping
 ) -> Optional[RequiredAnnotation]:
-    parameterv1 = get_api_element_from_mapping(required_annotation, mapping, Parameter)
+    parameterv1 = get_annotated_api_element_by_type(
+        required_annotation, mapping.get_apiv1_elements(), Parameter
+    )
     if parameterv1 is None:
         return None
     type_and_same_value = _have_same_value(parameterv1, parameterv2)