feat(parser): explain why an annotation was generated automatically (#914)

* refactor(parser): improve readability

* feat(parser): explain autogenerated remove annotations

* feat(parser): explain autogenerated value annotations

* feat(parser): store match when creating enum type

* feat(parser): store match when creating boundary type

* feat(parser): explain enum annotations

* feat(parser): explain boundary annotations

* feat(parser): improve formatting of explanation

* chore(data): regenerate annotations

* refactor(parse): remove Type wrapper class

* fix(parser): mypy errors

* fix(parser): mypy errors

* fix(parser): mypy errors

* style: apply automatic fixes of linters

Co-authored-by: lars-reimann <[email protected]>

Author: lars-reimann

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

@@ -1,10 +1,12 @@
+from typing import Optional
+
 from package_parser.processing.annotations.model import (
     AnnotationStore,
     BoundaryAnnotation,
     Interval,
     ValueAnnotation,
 )
-from package_parser.processing.api.model import API
+from package_parser.processing.api.model import API, BoundaryType, UnionType
 
 from ._constants import autogen_author
 
@@ -25,23 +27,31 @@ def _generate_boundary_annotations(api: API, annotations: AnnotationStore) -> No
         ):
             continue
 
-        boundary_type = parameter.type.to_json()
-        if "kind" in boundary_type and boundary_type["kind"] == "UnionType":
-            union_type = boundary_type
-            for type_in_union in union_type["types"]:
-                if type_in_union["kind"] == "BoundaryType":
+        parameter_type = parameter.type
+        if parameter_type is None:
+            continue
+
+        boundary_type: Optional[BoundaryType] = None
+
+        if isinstance(parameter_type, UnionType):
+            for type_in_union in parameter_type.types:
+                if isinstance(type_in_union, BoundaryType):
                     boundary_type = type_in_union
-        if "kind" in boundary_type and boundary_type["kind"] == "BoundaryType":
-            min_value = boundary_type["min"]
-            max_value = boundary_type["max"]
 
-            is_discrete = boundary_type["base_type"] == "int"
+        if isinstance(parameter_type, BoundaryType):
+            boundary_type = parameter_type
+
+        if boundary_type is not None:
+            min_value = boundary_type.min
+            max_value = boundary_type.max
+
+            is_discrete = boundary_type.base_type == "int"
 
             min_limit_type = 0
             max_limit_type = 0
-            if not boundary_type["min_inclusive"]:
+            if not boundary_type.min_inclusive:
                 min_limit_type = 1
-            if not boundary_type["max_inclusive"]:
+            if not boundary_type.max_inclusive:
                 max_limit_type = 1
             if min_value == "NegativeInfinity":
                 min_value = 0
@@ -61,6 +71,7 @@ def _generate_boundary_annotations(api: API, annotations: AnnotationStore) -> No
                 target=parameter.id,
                 authors=[autogen_author],
                 reviewers=[],
+                comment=f"I turned this into a bounded number because the description contained {boundary_type.full_match}.",
                 interval=interval,
             )
             annotations.boundaryAnnotations.append(boundary)

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

@@ -6,7 +6,7 @@
     EnumPair,
     ValueAnnotation,
 )
-from package_parser.processing.api.model import API
+from package_parser.processing.api.model import API, EnumType, UnionType
 
 from ._constants import autogen_author
 
@@ -27,26 +27,21 @@ def _generate_enum_annotations(api: API, annotations: AnnotationStore) -> None:
         ):
             continue
 
-        enum_type = parameter.type.to_json()
+        parameter_type = parameter.type
+        if parameter_type is None:
+            continue
+
         pairs = []
-        if "kind" in enum_type and enum_type["kind"] == "UnionType":
-            for type_in_union in enum_type["types"]:
-                if type_in_union["kind"] == "EnumType":
-                    values = sorted(list(type_in_union["values"]))
-                    for string_value in values:
-                        instance_name = _enum_instance_name(string_value)
-                        pairs.append(
-                            EnumPair(
-                                stringValue=string_value, instanceName=instance_name
-                            )
-                        )
-        elif "kind" in enum_type and enum_type["kind"] == "EnumType":
-            values = sorted(list(enum_type["values"]))
-            for string_value in values:
-                instance_name = _enum_instance_name(string_value)
-                pairs.append(
-                    EnumPair(stringValue=string_value, instanceName=instance_name)
-                )
+        full_match = ""
+        if isinstance(parameter_type, UnionType):
+            for type_in_union in parameter_type.types:
+                if isinstance(type_in_union, EnumType):
+                    pairs = _enum_pairs(type_in_union)
+                    full_match = type_in_union.full_match
+
+        elif isinstance(parameter_type, EnumType):
+            pairs = _enum_pairs(parameter_type)
+            full_match = parameter_type.full_match
 
         if len(pairs) > 0:
             enum_name = _enum_name(parameter.name)
@@ -55,6 +50,7 @@ def _generate_enum_annotations(api: API, annotations: AnnotationStore) -> None:
                     target=parameter.id,
                     authors=[autogen_author],
                     reviewers=[],
+                    comment=f"I turned this into an enum because the type in the documentation contained {full_match}.",
                     enumName=enum_name,
                     pairs=pairs,
                 )
@@ -67,6 +63,17 @@ def _enum_name(parameter_name: str) -> str:
     return "".join([segment.capitalize() for segment in segments if segment != ""])
 
 
+def _enum_pairs(enum_type: EnumType) -> list[EnumPair]:
+    result = []
+
+    sorted_values = sorted(list(enum_type.values))
+    for string_value in sorted_values:
+        instance_name = _enum_instance_name(string_value)
+        result.append(EnumPair(stringValue=string_value, instanceName=instance_name))
+
+    return result
+
+
 def _enum_instance_name(string_value: str) -> str:
     segments = re.split(r"[_\-.]", string_value)
 

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

@@ -18,17 +18,38 @@ def _generate_remove_annotations(
     :param annotations: AnnotationStore object
     """
     for class_ in api.classes.values():
-        if usages.n_class_usages(class_.id) == 0:
+        n_class_usages = usages.n_class_usages(class_.id)
+        if n_class_usages == 0:
             annotations.removeAnnotations.append(
                 RemoveAnnotation(
-                    target=class_.id, authors=[autogen_author], reviewers=[]
+                    target=class_.id,
+                    authors=[autogen_author],
+                    reviewers=[],
+                    comment=_create_explanation("class", n_class_usages),
                 )
             )
 
     for function in api.functions.values():
-        if usages.n_function_usages(function.id) == 0:
+        n_function_usages = usages.n_function_usages(function.id)
+        if n_function_usages == 0:
             annotations.removeAnnotations.append(
                 RemoveAnnotation(
-                    target=function.id, authors=[autogen_author], reviewers=[]
+                    target=function.id,
+                    authors=[autogen_author],
+                    reviewers=[],
+                    comment=_create_explanation("function", n_function_usages),
                 )
             )
+
+
+def _create_explanation(declaration_type: str, n_usages: int) -> str:
+    result = f"I removed this {declaration_type} because it has"
+
+    if n_usages == 0:
+        result += " no known usages."
+    elif n_usages == 1:
+        result += " only one known usage."
+    else:
+        result += f" only {n_usages} known usages."
+
+    return result

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

@@ -11,6 +11,7 @@
 from package_parser.processing.usages.model import UsageCountStore
 from scipy.stats import binom
 
+from ...utils import pluralize
 from ._constants import autogen_author
 
 
@@ -53,6 +54,7 @@ def _generate_constant_annotation(
                 target=parameter.id,
                 authors=[autogen_author],
                 reviewers=[],
+                comment=f"I replaced this parameter with a constant because it is always set to the same literal value ({sole_stringified_value}).",
                 defaultValueType=default_value_type,
                 defaultValue=default_value,
             )
@@ -63,6 +65,7 @@ def _generate_constant_annotation(
                 target=parameter.id,
                 authors=[autogen_author],
                 reviewers=[],
+                comment=f"I made this parameter required because, even though it is always set to the same value ({sole_stringified_value}), that value is not a literal.",
             )
         )
 
@@ -78,7 +81,10 @@ def _generate_required_or_optional_annotation(
     if not _is_stringified_literal(most_common_values[0]):
         annotations.valueAnnotations.append(
             RequiredAnnotation(
-                target=parameter.id, authors=[autogen_author], reviewers=[]
+                target=parameter.id,
+                authors=[autogen_author],
+                reviewers=[],
+                comment=f"I made this parameter required because the most common value ({most_common_values[0]}) is not a literal.",
             )
         )
         return
@@ -90,10 +96,19 @@ def _generate_required_or_optional_annotation(
     )
 
     # Add appropriate annotation
-    if _should_be_required(most_common_value_count, second_most_common_value_count):
+    should_be_required, comment = _should_be_required(
+        most_common_values[0],
+        most_common_value_count,
+        most_common_values[1],
+        second_most_common_value_count,
+    )
+    if should_be_required:
         annotations.valueAnnotations.append(
             RequiredAnnotation(
-                target=parameter.id, authors=[autogen_author], reviewers=[]
+                target=parameter.id,
+                authors=[autogen_author],
+                reviewers=[],
+                comment=comment,
             )
         )
     else:
@@ -107,25 +122,33 @@ def _generate_required_or_optional_annotation(
                     target=parameter.id,
                     authors=[autogen_author],
                     reviewers=[],
+                    comment=comment,
                     defaultValueType=default_value_type,
                     defaultValue=default_value,
                 )
             )
 
 
 def _should_be_required(
-    most_common_value_count: int, second_most_common_value_count: int
-) -> bool:
+    most_common_value: str,
+    most_common_value_count: int,
+    second_most_common_value: str,
+    second_most_common_value_count: int,
+) -> tuple[bool, str]:
     """
     This function determines how to differentiate between an optional and a required parameter
     :param most_common_value_count: How often the most common value is used
     :param second_most_common_value_count: How often the second most common value is used
-    :return: True means the parameter should be required, False means it should be optional
+    :return: True means the parameter should be required, False means it should be optional. The second result is an
+    explanation.
     """
 
     # Shortcut to speed up the check
     if most_common_value_count == second_most_common_value_count:
-        return True
+        return (
+            True,
+            f"I made this parameter required because there is no single most common value ({most_common_value} and {second_most_common_value} are both used {pluralize(most_common_value_count, 'time')}).",
+        )
 
     # Precaution to ensure proper order of most_common_value_count and second_most_common_value_count
     if second_most_common_value_count > most_common_value_count:
@@ -140,13 +163,21 @@ def _should_be_required(
     # toss. Unless this hypothesis is rejected, we make the parameter required. We reject the hypothesis if the p-value
     # is less than or equal to 5%. The p-value is the probability that we observe results that are at least as extreme
     # as the values we observed, assuming the null hypothesis is true.
-    return (
-        2
-        * sum(
-            binom.pmf(i, total, 0.5) for i in range(most_common_value_count, total + 1)
-        )
-        > 0.05
+    p_value = 2 * sum(
+        binom.pmf(i, total, 0.5) for i in range(most_common_value_count, total + 1)
     )
+    significance_level = 0.05
+
+    if p_value <= significance_level:
+        return (
+            False,
+            f"I made this parameter optional because there is a statistically significant most common value (p-value {p_value:.2%} <= significance level {significance_level:.0%}).",
+        )
+    else:
+        return (
+            True,
+            f"I made this parameter required because there is no statistically significant most common value (p-value ({p_value:.2%}) > significance level ({significance_level:.0%}).",
+        )
 
 
 def _is_stringified_literal(stringified_value: str) -> bool:

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

@@ -1,7 +1,7 @@
 from abc import ABC
 from dataclasses import asdict, dataclass
 from enum import Enum
-from typing import Any
+from typing import Any, Union
 
 ANNOTATION_SCHEMA_VERSION = 2
 
@@ -11,6 +11,7 @@ class AbstractAnnotation(ABC):
     target: str
     authors: list[str]
     reviewers: list[str]
+    comment: str
 
     def to_json(self) -> dict:
         return asdict(self)
@@ -24,9 +25,9 @@ class RemoveAnnotation(AbstractAnnotation):
 @dataclass
 class Interval:
     isDiscrete: bool
-    lowerIntervalLimit: int
+    lowerIntervalLimit: Union[int, float, str]
     lowerLimitType: int
-    upperIntervalLimit: int
+    upperIntervalLimit: Union[int, float, str]
     upperLimitType: int
 
     def to_json(self) -> dict:
@@ -79,6 +80,7 @@ def to_json(self) -> dict:
             "target": self.target,
             "authors": self.authors,
             "reviewers": self.reviewers,
+            "comment": self.comment,
             "variant": self.variant.value,
             "defaultValueType": self.defaultValueType.value,
             "defaultValue": self.defaultValue,
@@ -96,6 +98,7 @@ def to_json(self) -> dict:
             "target": self.target,
             "authors": self.authors,
             "reviewers": self.reviewers,
+            "comment": self.comment,
             "variant": self.variant.value,
             "defaultValueType": self.defaultValueType.value,
             "defaultValue": self.defaultValue,
@@ -111,6 +114,7 @@ def to_json(self) -> dict:
             "target": self.target,
             "authors": self.authors,
             "reviewers": self.reviewers,
+            "comment": self.comment,
             "variant": self.variant.value,
         }
 

package-parser/package_parser/processing/api/model/__init__.py

@@ -15,4 +15,11 @@
     ParameterDocumentation,
 )
 from ._parameters import Parameter, ParameterAssignment
-from ._types import AbstractType, BoundaryType, EnumType, NamedType, Type, UnionType
+from ._types import (
+    AbstractType,
+    BoundaryType,
+    EnumType,
+    NamedType,
+    UnionType,
+    create_type,
+)