feat: improve migration of annotations (#1163)

Closes #1162.

### Summary of Changes
some improvements at the migration of annotations:
- output the migrated annotations in different files based on the
similarity
- remove duplicates (same target and same semantic meaning) in both
annotation stores
- migrate `@value` annotations if type or value is not correct if the
annotated apiv1 element has the same type or value
- migrate not unsure annotations if both types of the elements are None
- do not migrate unsure `@todo` annotations, but with none as review
result

### Testing Instructions

run `migrate` command or run the tests in
`package-parser/tests/processing/migration/test_migration.py`

Author: Aclrian

.github/workflows/main.yml

@@ -97,6 +97,9 @@ jobs:
       - name: Smoke test (all)
         run: poetry run parse-package all -p package_parser -s package_parser -c package_parser -o out
 
+      - name: Smoke test (migration)
+        run: poetry run parse-package migrate -a1 tests/data/migration/apiv1_data.json -a2 tests/data/migration/apiv2_data.json -a tests/data/migration/annotationv1.json -o out
+
       # Requires installation of pytest and pytest-cov
       - name: Test with pytest
         run: poetry run pytest --doctest-modules

package-parser/package_parser/cli/_run_migrate.py

@@ -1,6 +1,7 @@
+import os
 from pathlib import Path
 
-from package_parser.processing.migration import migrate_annotations
+from package_parser.processing.migration import Migration
 from package_parser.processing.migration.model import APIMapping, SimpleDiffer
 
 from ._read_and_write_file import (
@@ -22,5 +23,19 @@ def _run_migrate_command(
     differ = SimpleDiffer()
     api_mapping = APIMapping(apiv1, apiv2, differ)
     mappings = api_mapping.map_api()
-    annotationsv2 = migrate_annotations(annotationsv1, mappings)
-    _write_annotations_file(annotationsv2, out_dir_path)
+    migration = Migration(annotationsv1, mappings)
+    migration.migrate_annotations()
+    migrated_annotations_file = Path(
+        os.path.join(out_dir_path, "migrated_annotationsv" + apiv2.version + ".json")
+    )
+    unsure_migrated_annotations_file = Path(
+        os.path.join(
+            out_dir_path, "unsure_migrated_annotationsv" + apiv2.version + ".json"
+        )
+    )
+    _write_annotations_file(
+        migration.migrated_annotation_store, migrated_annotations_file
+    )
+    _write_annotations_file(
+        migration.unsure_migrated_annotation_store, unsure_migrated_annotations_file
+    )

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

@@ -1 +1,2 @@
+from ._are_semantic_equal import are_semantic_equal
 from ._generate_annotations import generate_annotations

package-parser/package_parser/processing/annotations/_are_semantic_equal.py

@@ -0,0 +1,109 @@
+from package_parser.processing.annotations.model import (
+    AbstractAnnotation,
+    BoundaryAnnotation,
+    CalledAfterAnnotation,
+    ConstantAnnotation,
+    DescriptionAnnotation,
+    EnumAnnotation,
+    ExpertAnnotation,
+    GroupAnnotation,
+    MoveAnnotation,
+    OmittedAnnotation,
+    OptionalAnnotation,
+    RemoveAnnotation,
+    RenameAnnotation,
+    RequiredAnnotation,
+    TodoAnnotation,
+    ValueAnnotation,
+)
+
+
+def are_semantic_equal(
+    annotation_a: AbstractAnnotation, annotation_b: AbstractAnnotation
+) -> bool:
+    if (
+        annotation_a.target == annotation_b.target
+        and isinstance(annotation_a, type(annotation_b))
+        and isinstance(annotation_b, type(annotation_a))
+    ):
+        if isinstance(annotation_a, BoundaryAnnotation) and isinstance(
+            annotation_b, BoundaryAnnotation
+        ):
+            return annotation_a.interval == annotation_b.interval
+        if isinstance(annotation_a, CalledAfterAnnotation) and isinstance(
+            annotation_b, CalledAfterAnnotation
+        ):
+            return annotation_a.calledAfterName == annotation_b.calledAfterName
+        if isinstance(annotation_a, DescriptionAnnotation) and isinstance(
+            annotation_b, DescriptionAnnotation
+        ):
+            return annotation_a.newDescription == annotation_b.newDescription
+        if (
+            isinstance(annotation_a, EnumAnnotation)
+            and isinstance(annotation_b, EnumAnnotation)
+            and annotation_a.enumName == annotation_b.enumName
+            and len(annotation_a.pairs) == len(annotation_a.pairs)
+        ):
+            list_a = sorted(list(annotation_a.pairs), key=lambda x: x.stringValue)
+            list_b = sorted(list(annotation_b.pairs), key=lambda x: x.stringValue)
+            for i in range(len(annotation_a.pairs)):
+                if (
+                    list_a[i].stringValue != list_b[i].stringValue
+                    or list_a[i].instanceName != list_b[i].instanceName
+                ):
+                    return False
+            return True
+        if isinstance(annotation_a, ExpertAnnotation) and isinstance(
+            annotation_b, ExpertAnnotation
+        ):
+            return True
+        if isinstance(annotation_a, GroupAnnotation) and isinstance(
+            annotation_b, GroupAnnotation
+        ):
+            return annotation_a.groupName == annotation_b.groupName and set(
+                annotation_a.parameters
+            ) == set(annotation_b.parameters)
+        if isinstance(annotation_a, MoveAnnotation) and isinstance(
+            annotation_b, MoveAnnotation
+        ):
+            return annotation_a.destination == annotation_b.destination
+        if isinstance(annotation_a, RemoveAnnotation) and isinstance(
+            annotation_b, RemoveAnnotation
+        ):
+            return True
+        if isinstance(annotation_a, RenameAnnotation) and isinstance(
+            annotation_b, RenameAnnotation
+        ):
+            return annotation_a.newName == annotation_b.newName
+        if isinstance(annotation_a, TodoAnnotation) and isinstance(
+            annotation_b, TodoAnnotation
+        ):
+            return annotation_a.newTodo == annotation_b.newTodo
+        if (
+            isinstance(annotation_a, ValueAnnotation)
+            and isinstance(annotation_b, ValueAnnotation)
+            and annotation_a.variant == annotation_b.variant
+        ):
+            if isinstance(annotation_a, ConstantAnnotation) and isinstance(
+                annotation_b, ConstantAnnotation
+            ):
+                return (
+                    annotation_a.defaultValue == annotation_b.defaultValue
+                    and annotation_a.defaultValueType == annotation_b.defaultValueType
+                )
+            if isinstance(annotation_a, OptionalAnnotation) and isinstance(
+                annotation_b, OptionalAnnotation
+            ):
+                return (
+                    annotation_a.defaultValue == annotation_b.defaultValue
+                    and annotation_a.defaultValueType == annotation_b.defaultValueType
+                )
+            if isinstance(annotation_a, OmittedAnnotation) and isinstance(
+                annotation_b, OmittedAnnotation
+            ):
+                return True
+            if isinstance(annotation_a, RequiredAnnotation) and isinstance(
+                annotation_b, RequiredAnnotation
+            ):
+                return True
+    return False

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

@@ -82,6 +82,18 @@ def from_json(json: Any) -> Interval:
             json["upperLimitType"],
         )
 
+    def __eq__(self, other: Any) -> bool:
+        return (
+            isinstance(other, Interval)
+            and self.isDiscrete == other.isDiscrete
+            and self.lowerIntervalLimit == other.lowerIntervalLimit
+            and isinstance(self.lowerIntervalLimit, type(self.lowerIntervalLimit))
+            and self.lowerLimitType == other.lowerLimitType
+            and self.upperIntervalLimit == other.upperIntervalLimit
+            and isinstance(self.upperIntervalLimit, type(self.upperIntervalLimit))
+            and self.upperLimitType == self.upperLimitType
+        )
+
 
 @dataclass
 class BoundaryAnnotation(AbstractAnnotation):
@@ -122,6 +134,13 @@ def to_json(self) -> dict:
     def from_json(json: Any) -> EnumPair:
         return EnumPair(json["stringValue"], json["instanceName"])
 
+    def __eq__(self, other: Any) -> bool:
+        return (
+            isinstance(other, EnumPair)
+            and self.stringValue == other.stringValue
+            and self.instanceName == other.instanceName
+        )
+
 
 @dataclass
 class EnumAnnotation(AbstractAnnotation):
@@ -311,7 +330,9 @@ class ParameterInfo:
     value: str
     value_type: str
 
-    def __init__(self, parameter_type, value="", value_type=""):
+    def __init__(
+        self, parameter_type: ParameterType, value: str = "", value_type: str = ""
+    ) -> None:
         self.type = parameter_type
         self.value = value
         self.value_type = value_type

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

@@ -9,4 +9,4 @@
     SimpleDiffer,
 )
 
-from ._migrate import migrate_annotations
+from ._migrate import Migration