Imports:
  - Types:
      - AST
    Usages:
      - loading
    From: goga/ast
  - Types:
      - contract AS contract_logic
    Usages:
      - contract AS use_contract
    From: goga/contract
  - Types:
      - Config
      - load_config
    Usages:
      - configuration
    From: goga/config

Usages:
  click: .goga/usages/cooks/click.md
  conventions: .goga/usages/conventions.md
  beautiful_json: .goga/usages/cooks/beautiful_json.md

Annotations: |
  The `conventions` practice is used for:
  - working with the codebase
  - organizing the REPL development cycle
  - debugging and testing
  - organizing test infrastructure
  - understanding general development and testing principles/rules in the project
  Use the `click` practice to create the command.
  Use the `use_contract` practice to understand the contract dispatcher.
  Configuration is loaded via `load_config` using the `configuration` practice.

---

"contract(cells: list[str], lang: str | None = None)":
  location: contract.py
  annotations: |
    Command for comparing CODEMANIFEST contract with implementation.

    `cells`: paths to cells for comparison, one or more
    `lang`: implementation language. Priority: CLI argument > `Config`. If None — taken from `Config`.lang

    CLI options:
    - --lang: implementation language. If not specified — the value from `Config`.lang is used

    Algorithm:
    1. Load configuration via `load_config` → `Config`
    2. Resolve language:
       - If `lang` is provided (not None) — use CLI value
       - Otherwise — use `Config`.lang
    3. Create `AST` object and load the project using the `loading` practice
    4. For each path from `cells`:
      - Find the document in the tree using the `loading` practice
      - Extract types from document body: entities and routines
      - Get the implemented contract via `contract_logic`
      - For each type from CODEMANIFEST find the match in implementation by name
      - Build comparison structure (CODEMANIFEST is primary)

    Key principle: CODEMANIFEST is the source of truth. Traversal goes by types,
    methods and properties from the contract. Implementation fills the implementation
    field or null if not found.

    For entity:
    - signature: constructor parameters from codemanifest and implementation
    - properties: for each property from codemanifest find in implementation
    - methods: for each method from codemanifest find in implementation

    For routine:
    - signature: full signature from codemanifest and implementation

    Output the result via the `beautiful_json` practice.

    Output format:
    ```
    {
      "norm/path/to/cell": {
        "TypeName": {
          "signature": { "codemanifest": "...", "implementation": "..." },
          "properties": { "name": { "codemanifest": "...", "implementation": "..." } },
          "methods": { "name": { "codemanifest": "...", "implementation": "..." } }
        },
        "RoutineName": {
          "signature": { "codemanifest": "...", "implementation": "..." }
        }
      }
    }
    ```

    Requirements:
    - output must contain nothing except the json structure
    - if cell path not found → output error to stderr and exit with code 1
    - output errors to stderr (click.echo with err=True)
    - exit code: 0 on success, 1 on error
    - command help must explain the response structure and options clearly for AI agents

---

Author: Goga
CreatedAt: 20/05/26

Description: |
  Command for comparing CODEMANIFEST contract with implementation