Imports:
  - Types:
      - ASTRule
    From: goga/ast/rules/base
  - Types:
      - DocumentRoot
    From: goga/ast/nodes

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

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

---

# ********************************* #
# Rules at the level of all documents #
# ********************************* #

"ASTRule::ImportsHasNotCyclicalDeps(tree: list[DocumentRoot], name: str = 'imports_has_not_cyclical_deps')":
  location: rules.py
  annotations: |
    Rule — no import in the document is part of a cycle.

    If the document has an import from a path and the document at that
    path also has an import from the current document — this is an error.

    Additional requirements:
    - The algorithm for looking up the document being imported during validation must run in O(1) time

    Error templates:
    - cycle: "Cyclical import: package '{doc_path}' and '{imported_path}' import from each other"

"ASTRule::ImportTypeExists(tree: list[DocumentRoot], name: str = 'import_type_exists')":
  location: rules.py
  annotations: |
    Rule — imported types via Imports must exist in the document specified in From.

    Requirements:
    - If the From path does not exist on the filesystem, the check is skipped

    Error templates:
    - not_found: "Type '{type_name}' imported from '{from_path}' is not defined in that package's CODEMANIFEST"

"ASTRule::EmbeddedTypeHasLowLevel(tree: list[DocumentRoot], name: str = 'embedded_type_has_low_level')":
  location: rules.py
  annotations: |
    Rule — all embedded types are located deeper in the filesystem hierarchy.

    Examples:
    - In this example level-1 can embed level-2, but level-2 cannot embed level-1
      root/
      ├── level-1/
      │   ├── level-2/
      │   │   ├── CODEMANIFEST
      │   └── CODEMANIFEST

    Error templates:
    - wrong_level: "Embedded {kind} '{name}' comes from '{source_path}', but can only be embedded from packages nested below '{current_path}'"

---

Author: Mikhail Trifonov
CreatedAt: 14/05/26

Description: |
  Validation rules at the AST tree level across all documents.
