---
name: code_entity
lang: py
domain: core
version: "1.0.0"
algebraic: product
definition: |
  @dataclass
  class CodeEntity:
      kind: str                    # "function" | "class" | "method" | "interface" | "type" | "struct" | "trait"
      name: str                    # nombre de la entidad
      start_line: int              # linea de inicio (1-based)
      end_line: int                # linea de fin (1-based)
      signature: str               # firma completa hasta el body
      docstring: str | None        # docstring/comment extraido
      language: str                # "python" | "go" | "typescript" | "rust" | "java" | "cpp"
      children: list[CodeEntity] = field(default_factory=list)
description: "Entidad de codigo extraida por analisis AST (tree-sitter). Representa una funcion, clase, metodo, tipo, interfaz, struct o trait encontrado en codigo fuente. Las clases contienen sus metodos como children."
tags: [ast, code, parsing, tree-sitter, symbol, entity, core]
uses_types: []
file_path: "python/types/core/code_entity.py"
---

## Propiedades

- `line_count -> int` (property) — numero de lineas de la entidad: `end_line - start_line + 1`
- `has_docstring -> bool` (property) — True si `docstring` es no nulo y no vacio

## Metodos

- `to_dict() -> dict` — serializa la entidad de forma recursiva, incluyendo `children`
- `from_dict(data: dict) -> CodeEntity` (classmethod) — deserializa desde un dict, reconstruyendo el arbol de children

## Valores esperados

| Campo | Valores |
|---|---|
| `kind` | `"function"`, `"class"`, `"method"`, `"interface"`, `"type"`, `"struct"`, `"trait"` |
| `language` | `"python"`, `"go"`, `"typescript"`, `"rust"`, `"java"`, `"cpp"` |

## Ejemplo

```python
from code_entity import CodeEntity

# Funcion standalone
fn = CodeEntity(
    kind="function",
    name="parse_file",
    start_line=10,
    end_line=35,
    signature="def parse_file(path: str) -> list[CodeEntity]:",
    docstring="Parsea un archivo de codigo y retorna sus entidades.",
    language="python",
)

print(fn.line_count)     # 26
print(fn.has_docstring)  # True

# Clase con metodos como children
cls = CodeEntity(
    kind="class",
    name="Parser",
    start_line=1,
    end_line=80,
    signature="class Parser:",
    docstring=None,
    language="python",
    children=[fn],
)

data = cls.to_dict()
restored = CodeEntity.from_dict(data)
assert restored.name == "Parser"
assert restored.children[0].name == "parse_file"
```

## Notas

- `signature` incluye decoradores/annotations en Python, generic params en TypeScript/Go, visibility modifiers en Java/Rust. Es todo el texto desde el inicio de la definicion hasta el inicio del body (excluyendo `:`).
- `docstring` es el primer string literal hijo en Python, el comentario `///` o `/** */` previo en otros lenguajes. Puede ser None si la entidad no esta documentada.
- `children` solo se usa para metodos dentro de clases/structs/traits/interfaces. Las funciones standalone tienen `children = []`.
- El arbol de children es un nivel de profundidad en la mayoria de los casos (clase -> metodos). Traits con associated types pueden tener mas niveles.
- Tipo pensado como resultado de `parse_code_ast()`. Util para indexar codigo, generar skeletons, extraer candidatos de repos externos y navegacion (jump to definition).
