feat: migrate @expert annotations (#1160)

Closes #1155.

### Summary of Changes
- add `expertAnnotations` to `AnnotationStore`
- add migration for `@expert` annotations to another version, with the
possibilities:
- If the codomain contains only one element, the annotation will be
migrated to that element.
- If one mapped apiv2 element has the same type as the annotated apiv1
element, the annotation will be migrated as expected.
    - Else, the element will be marked with a `@todo` annotation.

### Testing Instructions

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

Author: Aclrian

package-parser/package_parser/processing/annotations/model/_AnnotationStore.py

@@ -11,6 +11,7 @@
     CompleteAnnotation,
     DescriptionAnnotation,
     EnumAnnotation,
+    ExpertAnnotation,
     GroupAnnotation,
     MoveAnnotation,
     PureAnnotation,
@@ -28,6 +29,7 @@ class AnnotationStore:
     completeAnnotations: list[CompleteAnnotation] = field(default_factory=list)
     descriptionAnnotations: list[DescriptionAnnotation] = field(default_factory=list)
     enumAnnotations: list[EnumAnnotation] = field(default_factory=list)
+    expertAnnotations: list[ExpertAnnotation] = field(default_factory=list)
     groupAnnotations: list[GroupAnnotation] = field(default_factory=list)
     moveAnnotations: list[MoveAnnotation] = field(default_factory=list)
     pureAnnotations: list[PureAnnotation] = field(default_factory=list)
@@ -63,6 +65,10 @@ def from_json(json: Any) -> AnnotationStore:
         for annotation in json["enumAnnotations"].values():
             enumAnnotations.append(EnumAnnotation.from_json(annotation))
 
+        expertAnnotations = []
+        for annotation in json["expertAnnotations"].values():
+            expertAnnotations.append(ExpertAnnotation.from_json(annotation))
+
         groupAnnotations = []
         for annotation in json["groupAnnotations"].values():
             groupAnnotations.append(GroupAnnotation.from_json(annotation))
@@ -97,6 +103,7 @@ def from_json(json: Any) -> AnnotationStore:
             completeAnnotations,
             descriptionAnnotations,
             enumAnnotations,
+            expertAnnotations,
             groupAnnotations,
             moveAnnotations,
             pureAnnotations,
@@ -117,6 +124,8 @@ def add_annotation(self, annotation: AbstractAnnotation) -> None:
             self.descriptionAnnotations.append(annotation)
         elif isinstance(annotation, EnumAnnotation):
             self.enumAnnotations.append(annotation)
+        elif isinstance(annotation, ExpertAnnotation):
+            self.expertAnnotations.append(annotation)
         elif isinstance(annotation, GroupAnnotation):
             self.groupAnnotations.append(annotation)
         elif isinstance(annotation, MoveAnnotation):
@@ -155,6 +164,10 @@ def to_json(self) -> dict:
                 annotation.target: annotation.to_json()
                 for annotation in self.enumAnnotations
             },
+            "expertAnnotations": {
+                annotation.target: annotation.to_json()
+                for annotation in self.expertAnnotations
+            },
             "groupAnnotations": {
                 annotation.target: annotation.to_json()
                 for annotation in self.groupAnnotations

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

@@ -10,6 +10,7 @@
     migrate_called_after_annotation,
     migrate_description_annotation,
     migrate_enum_annotation,
+    migrate_expert_annotation,
     migrate_group_annotation,
     migrate_move_annotation,
     migrate_remove_annotation,
@@ -66,6 +67,12 @@ def migrate_annotations(
             for annotation in migrate_enum_annotation(enum_annotation, mapping):
                 migrated_annotation_store.add_annotation(annotation)
 
+    for expert_annotation in annotationsv1.expertAnnotations:
+        mapping = _get_mapping_from_annotation(expert_annotation, mappings)
+        if mapping is not None:
+            for annotation in migrate_expert_annotation(expert_annotation, mapping):
+                migrated_annotation_store.add_annotation(annotation)
+
     for group_annotation in annotationsv1.groupAnnotations:
         mapping = _get_mapping_from_annotation(group_annotation, mappings)
         if mapping is not None:

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

@@ -4,6 +4,7 @@
 from ._migrate_called_after_annotation import migrate_called_after_annotation
 from ._migrate_description_annotation import migrate_description_annotation
 from ._migrate_enum_annotation import migrate_enum_annotation
+from ._migrate_expert_annotation import migrate_expert_annotation
 from ._migrate_group_annotation import migrate_group_annotation
 from ._migrate_move_annotation import migrate_move_annotation
 from ._migrate_remove_annotation import migrate_remove_annotation

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

@@ -8,6 +8,7 @@
     ConstantAnnotation,
     DescriptionAnnotation,
     EnumAnnotation,
+    ExpertAnnotation,
     GroupAnnotation,
     MoveAnnotation,
     OptionalAnnotation,
@@ -28,7 +29,10 @@
 
 
 def _get_further_information(annotation: AbstractAnnotation) -> str:
-    if isinstance(annotation, (CompleteAnnotation, PureAnnotation, RemoveAnnotation)):
+    if isinstance(
+        annotation,
+        (CompleteAnnotation, ExpertAnnotation, PureAnnotation, RemoveAnnotation),
+    ):
         return ""
     if isinstance(annotation, BoundaryAnnotation):
         return " with the interval '" + str(annotation.interval.to_json()) + "'"

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

@@ -0,0 +1,68 @@
+from copy import deepcopy
+
+from package_parser.processing.annotations.model import (
+    AbstractAnnotation,
+    EnumReviewResult,
+    ExpertAnnotation,
+    TodoAnnotation,
+)
+from package_parser.processing.api.model import Attribute, 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 migrate_expert_annotation(
+    expert_annotation: ExpertAnnotation, mapping: Mapping
+) -> list[AbstractAnnotation]:
+    expert_annotation = deepcopy(expert_annotation)
+    authors = expert_annotation.authors
+    authors.append(migration_author)
+    expert_annotation.authors = authors
+    migrate_text = get_migration_text(expert_annotation, mapping)
+
+    if isinstance(mapping, (ManyToOneMapping, OneToOneMapping)):
+        element = mapping.get_apiv2_elements()[0]
+        if isinstance(element, (Attribute, Result)):
+            return []
+        expert_annotation.target = element.id
+        return [expert_annotation]
+
+    annotated_apiv1_element = get_annotated_api_element(
+        expert_annotation, mapping.get_apiv1_elements()
+    )
+    if annotated_apiv1_element is None:
+        return []
+
+    expert_annotations: list[AbstractAnnotation] = []
+    for element in mapping.get_apiv2_elements():
+        if isinstance(element, type(annotated_apiv1_element)) and not isinstance(
+            element, (Attribute, Result)
+        ):
+            expert_annotations.append(
+                ExpertAnnotation(
+                    element.id,
+                    authors,
+                    expert_annotation.reviewers,
+                    expert_annotation.comment,
+                    EnumReviewResult.NONE,
+                )
+            )
+        elif not isinstance(element, (Attribute, Result)):
+            expert_annotations.append(
+                TodoAnnotation(
+                    element.id,
+                    authors,
+                    expert_annotation.reviewers,
+                    expert_annotation.comment,
+                    EnumReviewResult.NONE,
+                    migrate_text,
+                )
+            )
+    return expert_annotations

package-parser/tests/processing/annotations/model/test_annotations.py

@@ -26,7 +26,7 @@
 )
 
 
-def test_annotation_store():
+def test_annotation_store() -> None:
     annotations = AnnotationStore()
     annotations.removeAnnotations.append(
         RemoveAnnotation(
@@ -168,6 +168,15 @@ def test_annotation_store():
             newTodo="TODO replace me",
         )
     )
+    annotations.expertAnnotations.append(
+        ExpertAnnotation(
+            target="test/expert",
+            authors=["$autogen$"],
+            reviewers=[],
+            comment="",
+            reviewResult=EnumReviewResult.NONE,
+        )
+    )
     json_store = {
         "schemaVersion": ANNOTATION_SCHEMA_VERSION,
         "boundaryAnnotations": {
@@ -197,6 +206,15 @@ def test_annotation_store():
                 "pairs": [{"instanceName": "test", "stringValue": "test"}],
             }
         },
+        "expertAnnotations": {
+            "test/expert": {
+                "target": "test/expert",
+                "authors": ["$autogen$"],
+                "reviewers": [],
+                "comment": "",
+                "reviewResult": "",
+            }
+        },
         "removeAnnotations": {
             "test/remove": {
                 "target": "test/remove",
@@ -653,7 +671,9 @@ def test_annotation_store():
         "test import and export of rename annotation",
         "test import and export of todo annotation",
     ],
-)
-def test_conversion_between_json_and_annotation(annotation: AbstractAnnotation, json):
+)  # type: ignore
+def test_conversion_between_json_and_annotation(
+    annotation: AbstractAnnotation, json: dict
+) -> None:
     assert annotation.to_json() == json
     assert type(annotation).from_json(json) == annotation