bib_ast.py — Script de análisis AST del Bibliotecario
Script Python que recorre el corpus de código fuente de CreaRack Pro y extrae un grafo de conocimiento estático mediante análisis de AST. Su salida (JSON) es consumida por bib_index_ast del servidor MCP workspace para construir el grafo que alimenta el Oráculo y las búsquedas de impacto.
Responsabilidad
bib_ast.py es el parser offline del Bibliotecario. Se ejecuta periódicamente (cron Hetzner) o manualmente vía --push para reindexar el grafo. No modifica código fuente ni tablas de aplicación; solo produce artefactos de conocimiento.
Nodos extraídos
| Tipo de nodo | Descripción |
|---|---|
module | Cada archivo .py procesado |
class | Clases con información de herencia |
method | Métodos de clase |
function | Funciones standalone |
Edge types soportados
| Edge type | Desde | Hacia | Descripción |
|---|---|---|---|
imports | módulo | módulo/símbolo | Import estático |
inherits | clase | clase base | Herencia de clase |
contains | clase/módulo | método/función | Contención estructural |
calls | función/método | función/método | Llamada directa detectada en AST |
reads_from | función/método | modelo Django | <Model>.objects.<READ_METHOD>(...) |
writes_to | función/método | modelo Django | <Model>.objects.<WRITE_METHOD>(...) |
triggers | función/método | modelo Django | @receiver(signal, sender=<Model>) |
Añadidos en s79 (2026-05-22, cherry-pick #4 Understand-Anything)
Los tres últimos edge types (reads_from, writes_to, triggers) fueron incorporados como cherry-pick #4 del proyecto Understand-Anything (scope reducido). Ver ADR [[decision—20260522—evaluacion-understand-anything-vs-bibliotecario]].
ORM Read methods detectados (reads_from):
filter, get, all, first, last, count, exists, values, values_list, only, defer, aggregate, annotate, select_related, prefetch_related, none, latest, earliest, in_bulk, iterator, raw
ORM Write methods detectados (writes_to):
create, bulk_create, update, delete, bulk_update, get_or_create, update_or_create, bulk_create_or_update
Signal receivers detectados (triggers):
Decorator @receiver(<signal>, sender=<Model>). Solo se genera edge cuando hay sender explícito (Name o string literal). Receivers sin sender no producen edge (señal global, sin modelo concreto).
Métricas post-s79
Smoke test sobre corpus completo (340 archivos .py, 7 apps):
| Métrica | Valor |
|---|---|
| Edges pre-cambio | ~5 984 |
| Edges post-cambio | ~6 644 |
| Nuevos edges | +660 |
reads_from nuevos | 516 |
writes_to nuevos | 143 |
triggers nuevos | 1 |
| Ratio enriquecimiento | ~10 % |
| Falsos positivos (muestra manual) | 0 |
Lógica de resolución de nombres
El visitor usa _resolve_name() para mapear alias de import al qualified name completo del modelo. El patrón ORM requiere al menos 3 segmentos (model_alias.objects.method) y que _resolve_name resuelva el alias — si no resuelve, el edge no se emite (conservador ante ambigüedades).
Edge types excluidos (scope reducido)
Los siguientes 5 edge types de Understand-Anything se descartaron conscientemente:
subscribes/publishes— requieren parsers no-Python (Dockerfile, docker-compose)middleware— sensible a frameworks externosdeploys— infraestructura, no AST Pythonserves— depende de Django Channels / Huey (externos)
Candidatos para iteración futura si emerge necesidad concreta en queries del Oráculo.
Modo de ejecución
# Estadísticas sin escribir
python scripts/bib_ast.py --stats
# Generar JSON de salida
python scripts/bib_ast.py --output graph.json
# Modo incremental con push al grafo
python scripts/bib_ast.py --push
# Procesar apps específicas
python scripts/bib_ast.py --apps racks,monitoring --pushPlan de restauración ante fallo
Si el cron Hetzner falla por bug en este script, el grafo queda obsoleto (no corrupto). Restore:
rsync -av /opt/biblioteca-crons-bak-20260522-pre-cherrypick/ <destino>
git revert 544548bVéase también
- [[decision—20260522—evaluacion-understand-anything-vs-bibliotecario]]