feat: migrate @CalledAfter annotations (#1152)

Closes #1150.

### Summary of Changes

- Migration of `@CalledAfter` annotations through a mapping from old api
elements to new api elements for the two function called before or
after.
If there is no mapping from the function called before to another
function in the class of the apiv2 element, an unsure `@CalledAfter`
annotation will be created with the same name as the function called
before.
Else, a `@CalledAfter` annotation will be created, if the called before
function is mapped to only one other function and the annotated apiv2
element is a function.
Otherwise, mark the mapped apiv2 elements with a `@todo` annotation.


### Testing Instructions

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

Co-authored-by: Aclrian <[email protected]>

Author: Aclrian

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

@@ -7,17 +7,14 @@
 from package_parser.processing.api.model import Attribute, Result
 from package_parser.processing.migration.annotations import (
     migrate_boundary_annotation,
+    migrate_called_after_annotation,
     migrate_enum_annotation,
+    migrate_move_annotation,
+    migrate_remove_annotation,
     migrate_rename_annotation,
     migrate_todo_annotation,
     migrate_value_annotation,
 )
-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
 
 
@@ -45,6 +42,14 @@ def migrate_annotations(
             for annotation in migrate_boundary_annotation(boundary_annotation, mapping):
                 migrated_annotation_store.add_annotation(annotation)
 
+    for called_after_annotation in annotationsv1.calledAfterAnnotations:
+        mapping = _get_mapping_from_annotation(called_after_annotation, mappings)
+        if mapping is not None:
+            for annotation in migrate_called_after_annotation(
+                called_after_annotation, mapping, mappings
+            ):
+                migrated_annotation_store.add_annotation(annotation)
+
     for enum_annotation in annotationsv1.enumAnnotations:
         mapping = _get_mapping_from_annotation(enum_annotation, mappings)
         if mapping is not None:

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

@@ -1,7 +1,10 @@
 from ._constants import migration_author
 from ._get_migration_text import get_migration_text
 from ._migrate_boundary_annotation import migrate_boundary_annotation
+from ._migrate_called_after_annotation import migrate_called_after_annotation
 from ._migrate_enum_annotation import migrate_enum_annotation
+from ._migrate_move_annotation import migrate_move_annotation
+from ._migrate_remove_annotation import migrate_remove_annotation
 from ._migrate_rename_annotation import migrate_rename_annotation
 from ._migrate_todo_annotation import migrate_todo_annotation
 from ._migrate_value_annotation import migrate_value_annotation

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

@@ -1,3 +1,5 @@
+from typing import Any, Sequence
+
 from package_parser.processing.annotations.model import (
     AbstractAnnotation,
     BoundaryAnnotation,
@@ -15,6 +17,13 @@
     TodoAnnotation,
     ValueAnnotation,
 )
+from package_parser.processing.api.model import (
+    Attribute,
+    Class,
+    Function,
+    Parameter,
+    Result,
+)
 from package_parser.processing.migration import Mapping
 
 
@@ -75,7 +84,9 @@ def _get_further_information(annotation: AbstractAnnotation) -> str:
     return " with the data '" + str(annotation.to_json()) + "'"
 
 
-def get_migration_text(annotation: AbstractAnnotation, mapping: Mapping) -> str:
+def get_migration_text(
+    annotation: AbstractAnnotation, mapping: Mapping, additional_information: Any = None
+) -> str:
     class_name = str(annotation.__class__.__name__)
     if class_name.endswith("Annotation"):
         class_name = class_name[:-10]
@@ -89,13 +100,29 @@ def get_migration_text(annotation: AbstractAnnotation, mapping: Mapping) -> str:
         " from the previous version was at '"
         + annotation.target
         + "' and the possible alternatives in the new version of the api are: "
-        + ", ".join(
-            map(
-                lambda api_element: api_element.id
-                if hasattr(api_element, "id")
-                else api_element.name,
-                mapping.get_apiv2_elements(),
+        + _list_api_elements(mapping.get_apiv2_elements())
+    )
+    if additional_information is not None and isinstance(additional_information, list):
+        functions = [
+            function
+            for function in additional_information
+            if isinstance(function, Function)
+        ]
+        if len(functions) > 0:
+            migrate_text += (
+                " and the possible replacements (" + _list_api_elements(functions) + ")"
             )
+    return migrate_text
+
+
+def _list_api_elements(
+    api_elements: Sequence[Attribute | Class | Function | Parameter | Result],
+) -> str:
+    return ", ".join(
+        map(
+            lambda api_element: api_element.id
+            if hasattr(api_element, "id")
+            else api_element.name,
+            api_elements,
         )
     )
-    return migrate_text

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

@@ -0,0 +1,114 @@
+from copy import deepcopy
+
+from package_parser.processing.annotations.model import (
+    AbstractAnnotation,
+    CalledAfterAnnotation,
+    EnumReviewResult,
+    TodoAnnotation,
+)
+from package_parser.processing.api.model import Attribute, Function, Result
+from package_parser.processing.migration.model import Mapping
+
+from ._constants import migration_author
+from ._get_migration_text import get_migration_text
+
+
+def migrate_called_after_annotation(
+    called_after_annotation: CalledAfterAnnotation,
+    mapping: Mapping,
+    mappings: list[Mapping],
+) -> list[AbstractAnnotation]:
+    called_after_annotation = deepcopy(called_after_annotation)
+    authors = called_after_annotation.authors
+    authors.append(migration_author)
+    called_after_annotation.authors = authors
+
+    migrated_annotations: list[AbstractAnnotation] = []
+    for element in mapping.get_apiv2_elements():
+        if not isinstance(element, Function):
+            if not isinstance(element, (Attribute, Result)):
+                migrated_annotations.append(
+                    TodoAnnotation(
+                        element.id,
+                        authors,
+                        called_after_annotation.reviewers,
+                        called_after_annotation.comment,
+                        called_after_annotation.reviewResult,
+                        get_migration_text(called_after_annotation, mapping),
+                    )
+                )
+            continue
+
+        called_before_functions = _get_function_called_before_replacements(
+            called_after_annotation, mappings, element
+        )
+        migrate_text = get_migration_text(
+            called_after_annotation,
+            mapping,
+            additional_information=called_before_functions,
+        )
+        if len(called_before_functions) == 0:
+            migrated_annotations.append(
+                CalledAfterAnnotation(
+                    element.id,
+                    authors,
+                    called_after_annotation.reviewers,
+                    called_after_annotation.comment,
+                    EnumReviewResult.UNSURE,
+                    called_after_annotation.calledAfterName,
+                )
+            )
+        elif (
+            len(called_before_functions) == 1 and called_before_functions[0] != element
+        ):
+            migrated_annotations.append(
+                CalledAfterAnnotation(
+                    element.id,
+                    authors,
+                    called_after_annotation.reviewers,
+                    called_after_annotation.comment,
+                    called_after_annotation.reviewResult,
+                    called_before_functions[0].name,
+                )
+            )
+        else:
+            migrated_annotations.append(
+                TodoAnnotation(
+                    element.id,
+                    authors,
+                    called_after_annotation.reviewers,
+                    called_after_annotation.comment,
+                    EnumReviewResult.NONE,
+                    migrate_text,
+                )
+            )
+    return migrated_annotations
+
+
+def _get_function_called_before_replacements(
+    called_after_annotation: CalledAfterAnnotation,
+    mappings: list[Mapping],
+    functionv2: Function,
+) -> list[Function]:
+    called_before_idv1 = (
+        "/".join(called_after_annotation.target.split("/")[:-1])
+        + "/"
+        + called_after_annotation.calledAfterName
+    )
+    called_before_idv2_prefix = "/".join(functionv2.id.split("/")[:-1]) + "/"
+    functions_in_same_class: list[Function] = []
+    for mapping in mappings:
+        found_mapped_function_in_same_class = False
+        for element in mapping.get_apiv1_elements():
+            if isinstance(element, Function) and called_before_idv1 == element.id:
+                found_mapped_function_in_same_class = True
+                break
+
+        if found_mapped_function_in_same_class:
+            for replacement in mapping.get_apiv2_elements():
+                if isinstance(replacement, Function) and replacement.id.startswith(
+                    called_before_idv2_prefix
+                ):
+                    functions_in_same_class.append(replacement)
+            break
+    return functions_in_same_class

package-parser/tests/processing/migration/annotations/test_boundary_migration.py

@@ -30,7 +30,7 @@ def migrate_boundary_annotation_data_one_to_one_mapping() -> Tuple[
     parameterv1 = Parameter(
         id_="test/test.boundary.test1.testA",
         name="testA",
-        qname="test.enum.test1.testA",
+        qname="test.boundary.test1.testA",
         default_value="1",
         assigned_by=ParameterAssignment.POSITION_OR_NAME,
         is_public=True,
@@ -39,7 +39,7 @@ def migrate_boundary_annotation_data_one_to_one_mapping() -> Tuple[
     parameterv2 = Parameter(
         id_="test/test.boundary.test1.testB",
         name="testB",
-        qname="test.enum.test1.testB",
+        qname="test.boundary.test1.testB",
         default_value="1",
         assigned_by=ParameterAssignment.POSITION_OR_NAME,
         is_public=True,
@@ -88,7 +88,7 @@ def migrate_boundary_annotation_data_one_to_one_mapping_int_to_float() -> Tuple[
     parameterv1 = Parameter(
         id_="test/test.boundary.test2.testA",
         name="testA",
-        qname="test.enum.test2.testA",
+        qname="test.boundary.test2.testA",
         default_value="1",
         assigned_by=ParameterAssignment.POSITION_OR_NAME,
         is_public=True,
@@ -97,7 +97,7 @@ def migrate_boundary_annotation_data_one_to_one_mapping_int_to_float() -> Tuple[
     parameterv2 = Parameter(
         id_="test/test.boundary.test2.testB",
         name="testB",
-        qname="test.enum.test2.testB",
+        qname="test.boundary.test2.testB",
         default_value="1.0",
         assigned_by=ParameterAssignment.POSITION_OR_NAME,
         is_public=True,
@@ -152,7 +152,7 @@ def migrate_boundary_annotation_data_one_to_one_mapping_float_to_int() -> Tuple[
     parameterv1 = Parameter(
         id_="test/test.boundary.test3.testA",
         name="testA",
-        qname="test.enum.test3.testA",
+        qname="test.boundary.test3.testA",
         default_value="1.0",
         assigned_by=ParameterAssignment.POSITION_OR_NAME,
         is_public=True,
@@ -163,7 +163,7 @@ def migrate_boundary_annotation_data_one_to_one_mapping_float_to_int() -> Tuple[
     parameterv2 = Parameter(
         id_="test/test.boundary.test3.testB",
         name="testB",
-        qname="test.enum.test3.testB",
+        qname="test.boundary.test3.testB",
         default_value="1",
         assigned_by=ParameterAssignment.POSITION_OR_NAME,
         is_public=True,
@@ -215,7 +215,7 @@ def migrate_boundary_annotation_data_one_to_many_mapping() -> Tuple[
     parameterv1 = Parameter(
         id_="test/test.boundary.test4.testv1",
         name="testA",
-        qname="test.enum.test4.testA",
+        qname="test.boundary.test4.testA",
         default_value="1",
         assigned_by=ParameterAssignment.POSITION_OR_NAME,
         is_public=True,
@@ -224,7 +224,7 @@ def migrate_boundary_annotation_data_one_to_many_mapping() -> Tuple[
     parameterv2_a = Parameter(
         id_="test/test.boundary.test4.testA",
         name="testA",
-        qname="test.enum.test4.testA",
+        qname="test.boundary.test4.testA",
         default_value="1",
         assigned_by=ParameterAssignment.POSITION_OR_NAME,
         is_public=True,
@@ -233,7 +233,7 @@ def migrate_boundary_annotation_data_one_to_many_mapping() -> Tuple[
     parameterv2_b = Parameter(
         id_="test/test.boundary.test4.testB",
         name="testB",
-        qname="test.enum.test4.testB",
+        qname="test.boundary.test4.testB",
         default_value="1.0",
         assigned_by=ParameterAssignment.POSITION_OR_NAME,
         is_public=True,
@@ -244,7 +244,7 @@ def migrate_boundary_annotation_data_one_to_many_mapping() -> Tuple[
     parameterv2_c = Parameter(
         id_="test/test.boundary.test4.testC",
         name="testC",
-        qname="test.enum.test4.testC",
+        qname="test.boundary.test4.testC",
         default_value="",
         assigned_by=ParameterAssignment.POSITION_OR_NAME,
         is_public=True,