# ******************************************************************* #
# Defines the factory for building a CODEMANIFEST document node tree #
# ******************************************************************* #

Imports:
  - Types:
      - Node
      - DocumentRoot
      - HeaderNode
      - ImportsNode
      - ImportTypeItemNode
      - ImportUsageItemNode
      - UsagesNode
      - AnnotationsNode
      - BodyNode
      - RoutineTypeNode
      - EntityTypeNode
      - FooterNode
    From: goga/ast/nodes
  - Types:
      - DocumentParseError
    From: goga/ast/errors

Usages:
  dsl: https://raw.githubusercontent.com/qarium/codemanifest/refs/heads/0.0.x/specs/en.md
  conventions: .goga/usages/conventions.md
  yaml: |
    The pyyaml library for parsing YAML documents.
    The library must be listed as a project dependency.

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

  Use the practice `yaml` for loading documents.
  Use the practice `dsl` for YAML navigation.

  Build conventions:
    * Every created node contains data — the raw data from which it was created
    * Every created node contains parent — a reference to the parent node
    * Unknown keys in header and footer raise `DocumentParseError` listing
      all unknown keys
    * Value types are validated according to practice `dsl`

---

"Factory(path: str)":
  location: factory.py
  annotations: |
    Creates a document tree from a CODEMANIFEST YAML file.

    `path`: path to the directory containing the CODEMANIFEST file, relative to CWD

    The tree consists of a header (`HeaderNode`), body (`BodyNode`), and
    footer (`FooterNode`), combined into a root `DocumentRoot` node.

    Embedded types (prefix ->) are routed into embeddings as (name, path),
    and simultaneously added to entities/routines with the flag embedded=True.
  methods:
    "create(parent: Node = None) -> document:DocumentRoot": |
      Creates the document tree.

      `parent`: parent node
      `document`: the resulting document

      ## Header → `HeaderNode`

      Imports → `ImportsNode`:
      - Each type and usage in item is checked for alias and parsed with AS handling
      - Each imported type → a separate `ImportTypeItemNode`
      - Each imported usage → a separate `ImportUsageItemNode`

      Usages → `UsagesNode`:
      - Annotations are assembled into `AnnotationsNode`
      - File: .md suffix detected → store path without reading
      - URL: http/https prefix → store URL without fetching

      Annotations → `AnnotationsNode`:
      - String representation only
      - Link extraction (backtick) according to practice `dsl`

      Unknown keys → `DocumentParseError`

      ## Body → `BodyNode`

      Routines → `RoutineTypeNode` (only when no properties, methods, or mutations):
      - Signature is stored without name: "(param: str) -> void:null"
      - Prefix -> affects the embedded flag but is not part of the name

      Entities → `EntityTypeNode`:
      - Signature is stored without name: "(param: str) -> void:null"
      - File is converted from name to relative path from CWD
      - Prefix -> affects the embedded flag but is not part of the name
      - If no properties or methods but mutation exists → this is an entity

      ## Footer → `FooterNode`

      Unknown keys → `DocumentParseError`

---

Author: Mikhail Trifonov
CreatedAt: 11/04/26

Description: |
  Defines the factory for building a CODEMANIFEST document node tree.
