Imports:
  - Types:
      - DocumentRule
    From: goga/ast/rules/base
  - Types:
      - signature_contains_type_name
    From: goga/ast/rules/document/imports
  - Types:
      - AnnotationsNode
      - HeaderNode
      - UsageItemNode
      - RoutineTypeNode
      - EntityTypeNode
      - MethodNode
      - PropertyNode
      - BodyNode
    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`.

---

# ************ #
# Annotations  #
# ************ #

"DocumentRule::AnnotationLinksExists(name: str = 'annotation_links_exists')":
  location: rules.py
  annotations: |
    Validates link existence in `AnnotationsNode` for the following nodes:
    - `HeaderNode`
    - `UsageItemNode`
    - `RoutineTypeNode`
    - `EntityTypeNode`
    - `MethodNode`
    - `PropertyNode`

    At least one of the following must hold:
    - Link exists in `HeaderNode` imports as type or alias
    - Link exists in `HeaderNode` usages as name
    - Link exists in `BodyNode` as entity or routine name

    Additional rules:
    - In `EntityTypeNode`, `RoutineTypeNode`, `MethodNode` the link may exist in the signature

    Requirements:
    - Use `signature_contains_type_name` to search for links in signatures
    - Link search in signatures is a whole-word search, where delimiters can be spaces
      or punctuation (e.g. :), but not _ and - characters. In regex terms, this is
      a substring search that is not surrounded by [\w-] characters — the check must fail
      on param_ or param-, but pass on param:

    Error templates:
    - not_found: "Link `{link}` in {context} annotation does not match any import, usage, entity, routine, or signature parameter"

---

Author: Mikhail Trifonov
CreatedAt: 14/05/26

Description: |
  Validation rules for annotations in CODEMANIFEST documents.
