Imports:
  - Types:
      - DocumentRule
    From: goga/ast/rules/base
  - Types:
      - EntityTypeNode
      - RoutineTypeNode
      - MethodNode
      - 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`.

---

# ************************* #
# Entity / routine structure #
# ************************* #

"DocumentRule::EntitiesAndRoutinesHasNotConflicts(name: str = 'entities_and_routines_has_not_conflicts')":
  location: rules.py
  annotations: |
    Validates `EntityTypeNode` and `RoutineTypeNode`.

    Rules:
    - All entity and routine names must not conflict with imported type names in `ImportsNode`
      (conflicts can be resolved via type alias)

    Requirements:
    - Embedded types with flag embedded=True are exempt from this rule

    Error templates:
    - entity_conflict: "Entity '{entity_name}' has the same name as imported type '{type_name}' — use an alias in Imports to resolve"
    - routine_conflict: "Routine '{routine_name}' has the same name as imported type '{type_name}' — use an alias in Imports to resolve"

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

    Rules:
    - node.data contains only the following keys:
      - location
      - annotations
      - properties
      - methods

    Error templates:
    - unknown_keys: "Entity '{entity_name}' contains unknown keys {unknown_keys} — allowed: location, annotations, methods, properties"

"DocumentRule::RoutineHasOnlyValidKeys(name: str = 'routine_has_only_valid_keys')":
  location: rules.py
  annotations: |
    Validates `RoutineTypeNode`.

    Rules:
    - node.data contains only the following keys:
      - location
      - annotations

    Error templates:
    - unknown_keys: "Routine '{routine_name}' contains unknown keys {unknown_keys} — allowed: location, annotations"

"DocumentRule::SignatureIsValid(name: str = 'signature_is_valid')":
  location: rules.py
  annotations: |
    Validates `EntityTypeNode`, `RoutineTypeNode`, `MethodNode`.

    Rules:
    - Signature string matches the pattern '(...) -> ...' or '(...)'

    Error templates:
    - format: "signature '{signature_string}' has invalid format, use '(...) -> ...' or '(...)'"
    - empty: "signature is empty, use '(...) -> ...' or '(...)'"

"DocumentRule::ReturnTypeHasLink(name: str = 'return_type_has_link')":
  location: rules.py
  annotations: |
    Validates `EntityTypeNode` and `RoutineTypeNode`.

    Rules:
    - Return type in the signature has a link. Valid: -> label:Type. Invalid: -> Type

    Requirements:
    - A signature with no return type is a valid situation

    Error templates:
    - missing_link: "Return type '{return_part}' in '{signature}' is missing a semantic label — use format '-> label:Type'"

"DocumentRule::LocationIsRequired(name: str = 'location_is_required')":
  location: rules.py
  annotations: |
    Validates `EntityTypeNode` and `RoutineTypeNode`.

    Rules:
    - entity/routine contains location — filename with extension, without directories
    - Location contains an extension: has '.' and at least one character after '.'
    - Location does not contain '/'
    - Embedded types are skipped

    Error templates:
    - missing: "Type '{type_name}' in '{doc_path}' is missing required 'location' — specify the source file"
    - no_extension: "Type '{type_name}' in '{doc_path}' has location '{location_value}' without file extension — use format 'filename.ext'"
    - contains_path: "Type '{type_name}' in '{doc_path}' has location '{location_value}' containing directory path — use a plain filename without directories"

---

Author: Mikhail Trifonov
CreatedAt: 14/05/26

Description: |
  Validation rules for entity and routine structure in CODEMANIFEST documents.
