Imports:
  - Types:
      - DocumentRule
    From: goga/ast/rules/base
  - Types:
      - EntityTypeNode
      - ImportsNode
    From: goga/ast/nodes

Usages:
  conventions: .goga/usages/conventions.md

Annotations: |
  When developing and testing: follow the practice `conventions`.
  All types are mutations of `DocumentRule`.

---

# ********************* #
# Mutations and embeddings #
# ********************* #

"DocumentRule::MutationExists(name: str = 'mutation_exists')":
  location: rules.py
  annotations: |
    Validates `EntityTypeNode`.

    At least one of the following must hold:
    - All mutation_name (first element of tuple) exist among entity names
    - All mutation_name (first element of tuple) exist among routine names
    - All mutation_name (first element of tuple) exist among types in `ImportsNode` items

    Error templates:
    - not_found: "Base type '{mutation_name}' for mutation of '{entity_name}' not found in imports, entities, or routines of this package"

"DocumentRule::MutationIsValid(name: str = 'mutation_is_valid')":
  location: rules.py
  annotations: |
    Validates `EntityTypeNode`.

    Rules:
    - mutation_name (first element of tuple) must not match the entity name

    Error templates:
    - self_mutation: "Mutation '{mutation_name}' on '{entity_name}' references itself — a type cannot mutate from its own signature"

"DocumentRule::EmbeddedEntityCanNotHasMutations(name: str = 'embedded_entity_can_not_has_mutations')":
  location: rules.py
  annotations: |
    Validates `EntityTypeNode`.

    Rules:
    - Embedded entities must not define mutations

    Error templates:
    - has_mutations: "Embedded entity '{entity_name}' (->Entity) cannot define mutations — embedded types are included as-is from their source package"

---

Author: Mikhail Trifonov
CreatedAt: 14/05/26

Description: |
  Validation rules for mutations and embeddings in CODEMANIFEST documents.
