# ********************************************************* #
# Defines the data structures of nodes in a CODEMANIFEST document #
# ********************************************************* #

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

Annotations: |
  When developing and testing: follow the practice `conventions`.

---

Node():
  location: base.py
  properties:
    parent -> DocumentNode | DocumentRoot:
      Parent node or document
    data -> dict[str, Any]: |
      Raw data from which the node was created

Node::DocumentRoot():
  location: document.py
  properties:
    path -> str: |
      Relative path to the document's directory
    links -> dict[str, list[Node]]: |
      All links in the document mapped to the annotation nodes where they occur
    embeddings -> list[tuple[str, str]]: |
      List of (embedded type name, source path) tuples
    header -> HeaderNode: |
      Node containing the header content, default=HeaderNode()
    body -> BodyNode: |
      Node containing the body content, default=BodyNode()
    footer -> FooterNode: |
      Footer node of the document, default=FooterNode()
    types -> dict[str, list[Node]]: |
      All types in the document from header and body mapped to their nodes.
      For imported types, the node list is empty.
    children -> list[DocumentRoot]:
      Nested child documents

Node::DocumentNode():
  location: document.py
  properties:
    root -> DocumentRoot:
      The underlying document object

DocumentNode::AnnotationsNode():
  location: common.py
  properties:
    url -> str | None: |
      URL from which to load the usage
    filepath -> str | None: |
      Path to the annotation file
    links -> list[str]: |
      List of links in annotations
    text -> str: |
      Annotation text

DocumentNode::HeaderNode():
  location: header.py
  properties:
    imports -> ImportsNode: |
      List of imports in the document, default=ImportsNode()
    usages -> UsagesNode: |
      List of usages in the document, default=UsagesNode()
    annotations -> AnnotationsNode: |
      Annotations in the document
    types -> list[str]: |
      List of type names connected via imports

DocumentNode::ImportsNode():
  location: header.py
  properties:
    types -> list[ImportTypeItemNode]: |
      List of type imports
    usages -> list[ImportUsageItemNode]: |
      List of usage imports

DocumentNode::ImportTypeItemNode():
  location: header.py
  properties:
    type_name -> set[str]: |
      Name of the type to import
    from_path -> str: |
      Path to the cell to import the type from
    alias -> str: |
      Alias for the type name

DocumentNode::ImportUsageItemNode():
  location: header.py
  properties:
    usage_name -> set[str]: |
      Name of the usage to import
    from_path -> str: |
      Path to the cell to import the usage from
    alias -> str: |
      Alias for the type name

DocumentNode::UsagesNode():
  location: header.py
  properties:
    items -> list[UsageItemNode]: |
      List of usages

DocumentNode::UsageItemNode():
  location: header.py
  properties:
    name -> str: |
      Usage name
    annotations -> AnnotationsNode: |
      Usage annotations

DocumentNode::BodyNode():
  location: body.py
  properties:
    types -> dict[str, list[Node]]: |
      All types in the document mapped to their nodes.
    entities -> list[EntityTypeNode]: |
      List of entities in the document body
    routines -> list[RoutineTypeNode]: |
      List of routines in the document body

DocumentNode::RoutineTypeNode():
  location: body.py
  properties:
    name -> str: |
      Routine name
    signature -> str: |
      Routine signature string
    location -> str: |
      File where the routine is located
    annotations -> AnnotationsNode: |
      Routine annotations
    embedded -> bool: |
      Flag indicating whether the routine is embedded
      into the current document from another document

DocumentNode::EntityTypeNode():
  location: body.py
  properties:
    name -> str: |
      Entity name
    signature -> str: |
      Entity signature string
    location -> str: |
      File where the entity is located
    annotations -> AnnotationsNode: |
      Entity annotations
    properties -> list[PropertyNode]: |
      Entity properties
    methods -> list[MethodNode]: |
      List of entity methods
    embedded -> bool: |
      Flag indicating whether the entity is embedded
      into the current document from another document
    mutations -> list[tuple[str, str]]: |
      List of (base_type_name, document_path_where_mutation_is_declared) tuples

DocumentNode::MethodNode():
  location: body.py
  properties:
    name -> str: |
      Method name
    signature -> str: |
      Method signature string
    annotations -> AnnotationsNode: |
      Method annotations

DocumentNode::PropertyNode():
  location: body.py
  properties:
    name -> str: |
      Property name
    type -> str: |
      Property type
    annotations -> AnnotationsNode: |
      Property annotations

DocumentNode::FooterNode():
  location: footer.py
  properties:
    author -> str: |
      Author name
    created_at -> str: |
      Document creation date
    description -> str: |
      Document description

---

Author: Mikhail Trifonov
CreatedAt: 11/04/26

Description: |
  Defines the data structures of nodes in a CODEMANIFEST document.
