viv-compiler 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

viv_compiler/core/{validator.py → validation.py}

@@ -1,4 +1,4 @@
-"""A library of functions to validate preliminary action definitions and compiled content bundles.
+"""Module that handles validation of preliminary action definitions and compiled content bundles.
 
 The entrypoint functions are as follows:
     * `validate_join_directives()`: Invoked prior to handling of action inheritance.
@@ -19,31 +19,8 @@ from importlib import import_module
 from pydantic import TypeAdapter
 
 
-# todo do we already ensure all references are anchored in a (valid) role name?
-# todo warn or error if precondition references scaled enum?
-# todo validate time of day to ensure 0-23 and 0-59
-# todo technically you could inject major side effects (e.g. reaction queueing) into trope-fit expressions
-# todo ensure closing time period is always later than opening time period
-# todo ensure embargo is either permanent or has a declared time period
-# todo don't allow reaction to precast same entity multiple times
-# todo build roles:
-#  - they can cast exactly one entity, with no chance and no mean
-#  - no pool declarations
-#  - can never be precast
-#  - preconditions cannot reference build roles
-#  - don't allow them in embargoes (embargo would not be violable)
-# todo apparently the grammar allows e.g. multiple roles fields in an action definition
-#  - test what happens (presumably last in wins)
-# todo make sure times like 88:76 aren't allowed (grammar allows them)
-# todo role renaming (make sure new name being duplicate of existing one is already caught)
-#   - just detect duplicate role names right away post-visitor
-# todo prohibit entity references anchored in symbol roles
-#   - not ideal, but interpreter enforces this at runtime currently
-# todo assignments only allowed in scratch and effects
-
-
 def validate_join_directives(raw_action_definitions: list[viv_compiler.types.RawActionDefinition]) -> None:
-    """Ensure that the given action definition makes proper use of `join` directives.
+    """Make sure that the given action definition makes proper use of `join` directives.
 
     If this validation check passes, the given action definitions are ready for inheritance to be handled.
 
@@ -88,10 +65,10 @@ def validate_preliminary_action_definitions(
         Exception: At least one action definition did not pass validation.
     """
     for action_definition in intermediate_action_definitions:
-        # Ensure that a 'roles' field is present
+        # Make sure that a 'roles' field is present
         if "roles" not in action_definition:
             raise KeyError(f"Action '{action_definition['name']}' is missing a 'roles' field, which is required")
-        # Ensure that there is a single initiator role. Note that during initial validation,
+        # Make sure that there is a single initiator role. Note that during initial validation,
         # the 'roles' field is still a list.
         _detect_wrong_number_of_initiators(action_definition=action_definition)
         # Detect duplicated role names
@@ -160,7 +137,9 @@ def _detect_reference_to_undefined_role(action_definition: viv_compiler.types.In
         Exception: The action definition did not pass validation.
     """
     # Retrieve the names of all defined roles ('roles' is still a list at this point in postprocessing)
-    all_defined_role_names = {role['name'] for role in action_definition['roles']} | {'hearer', 'this', 'default'}
+    all_defined_role_names = (
+        {role['name'] for role in action_definition['roles']} | viv_compiler.config.SPECIAL_ROLE_NAMES
+    )
     # Validate report references
     if action_definition["report"]:
         for reference in viv_compiler.utils.get_all_referenced_roles(action_definition["report"]):
@@ -266,11 +245,25 @@ def _validate_trope_definitions(trope_definitions: dict[str, viv_compiler.types.
         # Detect any reference to an undefined param
         all_referenced_params = viv_compiler.utils.get_all_referenced_roles(ast_chunk=trope_definition)
         for referenced_param in all_referenced_params:
-            if referenced_param not in trope_definition["params"]:
+            if referenced_param not in [trope_param["name"] for trope_param in trope_definition["params"]]:
                 raise KeyError(
                     f"Trope '{trope_definition['name']}' references undefined parameter: "
                     f"'{referenced_param}'"
                 )
+        # Detect assignments, which are not allowed in trope bodies
+        assignments_in_trope_body = viv_compiler.utils.get_all_expressions_of_type(
+            expression_type=ExpressionDiscriminator.ASSIGNMENT,
+            ast_chunk=trope_definition
+        )
+        if assignments_in_trope_body:
+            raise ValueError(f"Trope '{trope_definition['name']}' has assignment in body (not allowed)")
+        # Detect reactions, which are not allowed in trope bodies
+        reactions_in_trope_body = viv_compiler.utils.get_all_expressions_of_type(
+            expression_type=ExpressionDiscriminator.REACTION,
+            ast_chunk=trope_definition
+        )
+        if reactions_in_trope_body:
+            raise ValueError(f"Trope '{trope_definition['name']}' has reaction in body (not allowed)")
 
 
 def _validate_action_definitions(
@@ -302,7 +295,10 @@ def _validate_action_definitions(
         _validate_action_effects(action_definition=action_definition)
         # Validate reactions
         _validate_action_reactions(action_definition=action_definition, all_action_definitions=action_definitions)
+        # Validate saliences
+        _validate_action_saliences(action_definition=action_definition)
         # Validate associations
+        _validate_action_associations(action_definition=action_definition)
         # Validate trope-fit expressions
         _validate_action_trope_fit_expressions(
             action_definition=action_definition,
@@ -314,6 +310,8 @@ def _validate_action_definitions(
         _validate_action_loops(action_definition=action_definition)
         # Validate assignments
         _validate_action_assignments(action_definition=action_definition)
+        # Validate references to scratch variables
+        _validate_scratch_variable_references(action_definition=action_definition)
         # Validate negated expressions
         _validate_negated_expressions(action_definition=action_definition)
         # Validate chance expressions
@@ -353,13 +351,13 @@ def _validate_action_roles(action_definition: viv_compiler.types.ActionDefinitio
     """
     # Validate the initiator role
     _validate_action_initiator_role(action_definition=action_definition)
-    # Ensure all roles have proper 'min' and 'max' values
+    # Make sure all roles have proper 'min' and 'max' values
     _validate_action_role_min_and_max_values(action_definition=action_definition)
-    # Ensure all roles have proper 'chance' and 'mean' values
+    # Make sure all roles have proper 'chance' and 'mean' values
     _validate_action_role_chance_and_mean_values(action_definition=action_definition)
-    # Ensure all roles with binding pools have proper ones
+    # Make sure all roles with binding pools have proper ones
     _validate_action_role_pool_directives(action_definition=action_definition)
-    # Ensure that the 'precast' label is only used if this is a special action
+    # Make sure that the 'precast' label is only used if this is a special action
     _validate_action_role_precast_label_usages(action_definition=action_definition)
 
 
@@ -377,13 +375,13 @@ def _validate_action_initiator_role(action_definition: viv_compiler.types.Action
     """
     # Retrieve the definition for the action's initiator role
     initiator_role_definition = action_definition['initiator']
-    # Ensure that the initiator role has no pool directive
+    # Make sure that the initiator role has no pool directive
     if initiator_role_definition["pool"]:
         raise ValueError(
             f"Action '{action_definition['name']}' has initiator role '{initiator_role_definition['name']}' "
             f"with a pool directive, which is not allowed for initiator roles"
         )
-    # Ensure that the initiator role casts exactly one entity
+    # Make sure that the initiator role casts exactly one entity
     if initiator_role_definition['min'] != 1:
         raise ValueError(
             f"Action '{action_definition['name']}' has initiator role '{initiator_role_definition['name']}' "
@@ -394,13 +392,13 @@ def _validate_action_initiator_role(action_definition: viv_compiler.types.Action
             f"Action '{action_definition['name']}' has initiator role '{initiator_role_definition['name']}' "
             f"with max other than 1 (there must be a single initiator)"
         )
-    # Ensure that the initiator role has no specified binding mean
+    # Make sure that the initiator role has no specified binding mean
     if initiator_role_definition['mean'] is not None:
         raise ValueError(
             f"Action '{action_definition['name']}' has initiator role '{initiator_role_definition['name']}' "
             f"with declared casting mean (there must be a single initiator)"
         )
-    # Ensure that the initiator role has no specified binding chance
+    # Make sure that the initiator role has no specified binding chance
     if initiator_role_definition['chance'] is not None:
         raise ValueError(
             f"Action '{action_definition['name']}' has initiator role '{initiator_role_definition['name']}' "
@@ -502,7 +500,7 @@ def _validate_action_role_pool_directives(action_definition: viv_compiler.types.
                 f"Action '{action_definition['name']}' has role '{role_definition['name']}' "
                 f"that requires a pool declaration but does not have one"
             )
-        # Ensure that all pool directives reference at most one other (valid) role
+        # Make sure that all pool directives reference at most one other (valid) role
         if role_definition["pool"]:
             all_pool_references = viv_compiler.utils.get_all_referenced_roles(role_definition["pool"])
             if len(all_pool_references) > 1:
@@ -627,25 +625,21 @@ def _validate_action_reactions(
     Raises:
         Exception: The action definition did not pass validation.
     """
-    # Ensure that all reactions are housed in the proper fields
-    fields_to_check = (
-        ("preconditions", action_definition["preconditions"]),
-        ("scratch", action_definition["scratch"]),
-        ("effects", action_definition["effects"]),
-    )
-    for field_name, field_value in fields_to_check:
-        reactions_in_this_field = viv_compiler.utils.get_all_expressions_of_type(
-            expression_type="reaction",
-            ast_chunk=field_value
-        )
-        if reactions_in_this_field:
-            raise ValueError(
-                f"Action '{action_definition['name']}' has reaction in '{field_name}' field "
-                f"(only allowed in 'reactions' field)"
+    # Make sure that all reactions are housed in the proper fields
+    for field_name, field_value in action_definition.items():
+        if field_name not in viv_compiler.config.ACTION_FIELDS_PERMITTING_REACTIONS:
+            reactions_in_this_field = viv_compiler.utils.get_all_expressions_of_type(
+                expression_type=ExpressionDiscriminator.REACTION,
+                ast_chunk=field_value
             )
+            if reactions_in_this_field:
+                raise ValueError(
+                    f"Action '{action_definition['name']}' has reaction in '{field_name}' field "
+                    f"(only allowed in 'reactions' field)"
+                )
     # Collect all reactions
     all_reactions = viv_compiler.utils.get_all_expressions_of_type(
-        expression_type="reaction",
+        expression_type=ExpressionDiscriminator.REACTION,
         ast_chunk=action_definition['reactions']
     )
     # Validate each reaction in turn
@@ -663,7 +657,7 @@ def _validate_action_reactions(
         queued_action_initiator_role_name = queued_action_definition['initiator']['name']
         initiator_is_bound = False
         for binding in reaction['bindings']:
-            if binding['value']['role'] == queued_action_initiator_role_name:
+            if binding['role'] == queued_action_initiator_role_name:
                 initiator_is_bound = True
                 break
         if not initiator_is_bound:
@@ -674,12 +668,21 @@ def _validate_action_reactions(
         # Make sure the reaction references only roles defined in the queued actions
         all_queued_action_role_names = queued_action_definition['roles'].keys()
         for binding in reaction['bindings']:
-            bound_role_name = binding['value']['role']
+            bound_role_name = binding['role']
             if bound_role_name not in all_queued_action_role_names:
                 raise KeyError(
                     f"Action '{action_definition['name']}' has '{queued_action_name}' reaction that "
                     f"references a role that is undefined for '{queued_action_name}': '{bound_role_name}'"
                 )
+        # Make sure that no role appears multiple times in the bindings
+        roles_already_precast = set()
+        for bindings in reaction['bindings']:
+            if bindings['role'] in roles_already_precast:
+                raise ValueError(
+                    f"Action '{action_definition['name']}' has '{queued_action_name}' reaction that "
+                    f"includes role '{queued_action_initiator_role_name}' in bindings more than once"
+                )
+            roles_already_precast.add(bindings['role'])
         # Make sure the reaction precasts all 'precast' roles
         for role_object in queued_action_definition['roles'].values():
             if not role_object['precast']:
@@ -687,7 +690,7 @@ def _validate_action_reactions(
             precast_role_name = role_object['name']
             role_is_precast = False
             for binding in reaction['bindings']:
-                bound_role_name = binding['value']['role']
+                bound_role_name = binding['role']
                 if bound_role_name == precast_role_name:
                     role_is_precast = True
                     break
@@ -698,6 +701,50 @@ def _validate_action_reactions(
                 )
 
 
+def _validate_action_saliences(action_definition: viv_compiler.types.ActionDefinition) -> None:
+    """Validate the given action definition's 'saliences' field.
+
+    Args:
+        action_definition: An action definition from a compiled content bundle.
+
+    Returns:
+        None.
+
+    Raises:
+        Exception: The action definition did not pass validation.
+    """
+    # Detect cases of a saliences variable shadowing the name of a role from the same action
+    all_role_names = viv_compiler.utils.get_all_role_names(action_definition=action_definition)
+    if action_definition['saliences']['variable']:
+        if action_definition['saliences']['variable']['name'] in all_role_names:
+            raise ValueError(
+                f"Action '{action_definition['name']}' has 'saliences' variable name that shadows role name "
+                f"'{action_definition['saliences']['variable']['name']}' (this is not allowed)"
+            )
+
+
+def _validate_action_associations(action_definition: viv_compiler.types.ActionDefinition) -> None:
+    """Validate the given action definition's 'associations' field.
+
+    Args:
+        action_definition: An action definition from a compiled content bundle.
+
+    Returns:
+        None.
+
+    Raises:
+        Exception: The action definition did not pass validation.
+    """
+    # Detect cases of an associations variable shadowing the name of a role from the same action
+    all_role_names = viv_compiler.utils.get_all_role_names(action_definition=action_definition)
+    if action_definition['associations']['variable']:
+        if action_definition['associations']['variable']['name'] in all_role_names:
+            raise ValueError(
+                f"Action '{action_definition['name']}' has 'associations' variable name that shadows role name "
+                f"'{action_definition['associations']['variable']['name']}' (this is not allowed)"
+            )
+
+
 def _validate_action_trope_fit_expressions(
     action_definition: viv_compiler.types.ActionDefinition,
     trope_definitions: dict[str, TropeDefinition]
@@ -715,7 +762,7 @@ def _validate_action_trope_fit_expressions(
         Exception: The action definition did not pass validation.
     """
     all_trope_fit_expressions = viv_compiler.utils.get_all_expressions_of_type(
-        expression_type="tropeFitExpression",
+        expression_type=ExpressionDiscriminator.TROPE_FIT_EXPRESSION,
         ast_chunk=action_definition
     )
     for trope_fit_expression in all_trope_fit_expressions:
@@ -748,21 +795,32 @@ def _validate_action_role_unpackings(action_definition: viv_compiler.types.Actio
     Raises:
         Exception: The action definition did not pass validation.
     """
-    # Ensure all role unpackings unpack roles that can cast multiple entities
+    # Retrieve all unpacked role names
     all_unpacked_role_names = viv_compiler.utils.get_all_expressions_of_type(
-        expression_type="roleUnpacking",
+        expression_type=ExpressionDiscriminator.ROLE_UNPACKING,
         ast_chunk=action_definition
     )
     for unpacked_role_name in all_unpacked_role_names:
+        if unpacked_role_name in viv_compiler.config.SPECIAL_ROLE_NAMES:
+            raise ValueError(
+                f"Action '{action_definition['name']}' unpacks a singleton role (one that is "
+                f"always bound to a single entity): '{unpacked_role_name}'"
+            )
+    # Make sure all role unpackings unpack roles that can cast multiple entities. Here, we'll also
+    # include all our special roles, since these are always singletons.
+    for unpacked_role_name in all_unpacked_role_names:
+        error_message = (
+            f"Action '{action_definition['name']}' unpacks a singleton role (one that is "
+            f"always bound to a single entity): '{unpacked_role_name}'"
+        )
+        if unpacked_role_name in viv_compiler.config.SPECIAL_ROLE_NAMES:
+            raise ValueError(error_message)
         for role_definition in action_definition['roles'].values():
             if role_definition['name'] == unpacked_role_name:
                 if role_definition['min'] == role_definition['max'] == 1:
-                    raise ValueError(
-                        f"Action '{action_definition['name']}' unpacks a singleton role (one that is "
-                        f"always bound to a single entity): '{unpacked_role_name}'"
-                    )
+                    raise ValueError(error_message)
                 break
-    # Ensure that all other references to roles that can cast multiple entities use role unpackings
+    # Make sure that all other references to roles that can cast multiple entities use role unpackings
     single_entity_role_references = viv_compiler.utils.get_all_referenced_roles(  # I.e., using the '@role' notation
         ast_chunk=action_definition,
         ignore_role_unpackings=True
@@ -792,7 +850,10 @@ def _validate_action_loops(action_definition: viv_compiler.types.ActionDefinitio
     Raises:
         Exception: The action definition did not pass validation.
     """
-    all_loops = viv_compiler.utils.get_all_expressions_of_type(expression_type="loop", ast_chunk=action_definition)
+    all_loops = viv_compiler.utils.get_all_expressions_of_type(
+        expression_type=ExpressionDiscriminator.LOOP,
+        ast_chunk=action_definition
+    )
     for loop in all_loops:
         # Detect attempts to loop over single-entity role references (i.e., ones using '@role' notation)
         if loop['iterable']['type'] == ExpressionDiscriminator.ENTITY_REFERENCE:
@@ -803,10 +864,10 @@ def _validate_action_loops(action_definition: viv_compiler.types.ActionDefinitio
                     f"role: '{role_name}' (perhaps use * instead of @)"
                 )
         # Detect cases of a loop variable shadowing the name of a role from the same action
-        if loop['variable'] in viv_compiler.utils.get_all_role_names(action_definition=action_definition):
+        if loop['variable']['name'] in viv_compiler.utils.get_all_role_names(action_definition=action_definition):
             raise ValueError(
                 f"Action '{action_definition['name']}' has loop with variable name that "
-                f"shadows role name '{loop['variable']}' (this is not allowed)"
+                f"shadows role name '{loop['variable']['name']}' (this is not allowed)"
             )
 
 
@@ -822,27 +883,48 @@ def _validate_action_assignments(action_definition: viv_compiler.types.ActionDef
     Raises:
         Exception: The action definition did not pass validation.
     """
+    # Make sure that all assignments are housed in the proper fields
+    for field_name, field_value in action_definition.items():
+        if field_name not in viv_compiler.config.ACTION_FIELDS_PERMITTING_ASSIGNMENTS:
+            assignments_in_field = viv_compiler.utils.get_all_expressions_of_type(
+                expression_type=ExpressionDiscriminator.ASSIGNMENT,
+                ast_chunk=field_value
+            )
+            if assignments_in_field:
+                raise ValueError(
+                    f"Action '{action_definition['name']}' has assignment in '{field_name}' field "
+                    f"(only allowed in {', '.join(viv_compiler.config.ACTION_FIELDS_PERMITTING_ASSIGNMENTS)})"
+                )
+    # Collect all assignments
     all_assignments = viv_compiler.utils.get_all_expressions_of_type(
-        expression_type="assignment",
+        expression_type=ExpressionDiscriminator.ASSIGNMENT,
         ast_chunk=action_definition
     )
+    # Validate each assignment in turn
     for assignment in all_assignments:
         anchor = assignment['left']['value']['anchor']
         path = assignment['left']['value']['path']
-        if assignment['left']['type'] == ExpressionDiscriminator.ENTITY_REFERENCE:
+        # Detect attempts to set a local variable. Note that we do allow assignments that are anchored
+        # in local variables and also have a path, since this enables the common pattern of looping
+        # over a role unpacking to execute effects for each entity cast in the group role.
+        if assignment['left']['value']['local'] and not path:
+            raise ValueError(
+                f"Assignment expression in action '{action_definition['name']}' sets local variable '{anchor}', "
+                f"but local variables can only be set in loops, 'saliences' headers, and 'associations' headers"
+            )
+        if anchor != viv_compiler.config.ACTION_SELF_REFERENCE_ROLE_NAME and anchor in action_definition['roles']:
             # Detect attempts to recast a role via assignment (not allowed)
             if not path:
                 raise ValueError(
                     f"Assignment expression in action '{action_definition['name']}' recasts "
                     f"role '{anchor}' (this is prohibited)"
                 )
-            # Detect attempts to set data on the "entity" associated with a symbol role
-            if anchor != "this":
-                if action_definition['roles'][anchor]['symbol']:
-                    raise ValueError(
-                        f"Assignment expression in action '{action_definition['name']}' has "
-                        f"symbol role on its left-hand side: '{anchor}'"
-                    )
+            # Detect attempts to set data on a complex symbol role (currently prohibited)
+            if action_definition['roles'][anchor]['symbol']:
+                raise ValueError(
+                    f"Assignment expression in action '{action_definition['name']}' has "
+                    f"symbol role on its left-hand side (this is currently prohibited): '{anchor}'"
+                )
         # Detect a trailing eval fail-safe marker, which is bizarre and probably an authoring error
         if path and path[-1].get('failSafe'):
             raise ValueError(
@@ -851,8 +933,11 @@ def _validate_action_assignments(action_definition: viv_compiler.types.ActionDef
             )
 
 
-def _validate_chance_expressions(action_definition: viv_compiler.types.ActionDefinition) -> None:
-    """Validate the given action definition's usage of chance expressions.
+def _validate_scratch_variable_references(action_definition: viv_compiler.types.ActionDefinition) -> None:
+    """Validate the given action definition's references to scratch variables.
+
+    This procedure ensures that any scratch variable that is referenced is assigned *somewhere* in
+    the action definition, but it does not ensure that the variable is assigned before it's used.
 
     Args:
         action_definition: An action definition from a compiled content bundle.
@@ -863,16 +948,22 @@ def _validate_chance_expressions(action_definition: viv_compiler.types.ActionDef
     Raises:
         Exception: The action definition did not pass validation.
     """
-    all_chance_expression_values = viv_compiler.utils.get_all_expressions_of_type(
-        expression_type="chanceExpression",
+    # Retrieve the names of all scratch variables that are set anywhere in the action definition
+    all_assigned_scratch_variable_names = set(viv_compiler.utils.get_all_assigned_scratch_variable_names(
         ast_chunk=action_definition
-    )
-    for chance_value in all_chance_expression_values:
-        if chance_value < 0.0 or chance_value > 1.0:
-            raise ValueError(
-                f"Chance expression in action '{action_definition['name']}' has "
-                f"chance value outside of the range [0, 1]: '{chance_value * 100}%'"
-            )
+    ))
+    # Retrieve the names of all scratch variables that are referenced anywhere in the action definition
+    all_referenced_scratch_variable_names = set(viv_compiler.utils.get_all_referenced_scratch_variable_names(
+        ast_chunk=action_definition
+    ))
+    # Flag any cases of a scratch variable being referenced without being assigned anywhere
+    referenced_but_not_assigned = all_referenced_scratch_variable_names - all_assigned_scratch_variable_names
+    if referenced_but_not_assigned:
+        snippet = "'" + "', '".join(sorted(referenced_but_not_assigned)) + "'"
+        raise ValueError(
+            f"Action '{action_definition['name']}' references the following scratch variables without ever "
+            f"assigning them: {snippet}"
+        )
 
 
 def _validate_negated_expressions(action_definition: viv_compiler.types.ActionDefinition) -> None:
@@ -896,6 +987,30 @@ def _validate_negated_expressions(action_definition: viv_compiler.types.ActionDe
             )
 
 
+def _validate_chance_expressions(action_definition: viv_compiler.types.ActionDefinition) -> None:
+    """Validate the given action definition's usage of chance expressions.
+
+    Args:
+        action_definition: An action definition from a compiled content bundle.
+
+    Returns:
+        None.
+
+    Raises:
+        Exception: The action definition did not pass validation.
+    """
+    all_chance_expression_values = viv_compiler.utils.get_all_expressions_of_type(
+        expression_type=ExpressionDiscriminator.CHANCE_EXPRESSION,
+        ast_chunk=action_definition
+    )
+    for chance_value in all_chance_expression_values:
+        if chance_value < 0.0 or chance_value > 1.0:
+            raise ValueError(
+                f"Chance expression in action '{action_definition['name']}' has "
+                f"chance value outside of the range [0, 1]: '{chance_value * 100}%'"
+            )
+
+
 def _validate_compiled_content_bundle_against_schema(content_bundle: viv_compiler.types.CompiledContentBundle) -> None:
     """Validate a compiled content bundle against its public schema.