Biblioteca Graphify — AST extractor

User value

Antes de Graphify, la Biblioteca era un grafo de 919 nodos y 1577 edges construido a mano: documentos, endpoints y anotaciones explícitas. El código Python — activo principal — era opaco. Cualquier pregunta sobre qué llama a qué, qué hereda de qué o qué módulos están acoplados requería leer archivos fuente.

Con Graphify el grafo pasó a 3090 nodos y 4450 edges automáticamente y sin dependencias externas. Los agentes consultan call graphs, detectan god nodes, calculan impacto de un cambio y descubren comunidades de código, todo via MCP, sin abrir un archivo.

Cómo usarla

# Extraer todo y enviar al MCP workspace
python scripts/bib_ast.py --push

# Solo una app (activa replace_app: borra nodos obsoletos)
python scripts/bib_ast.py --push --apps racks

# Modo incremental (cache SHA256)
python scripts/bib_ast.py --push --incremental

# Solo estadísticas
python scripts/bib_ast.py --stats

Token MCP leído de BIB_MCP_TOKEN. En producción el script corre cada 10 min via /etc/cron.d/bib-reindex en Hetzner Staging (scripts/cron-bib-reindex.sh), app por app con --apps <single> para activar replace_app y eliminar nodos fantasma.

Datos disponibles vía MCP tools: bib_call_graph, bib_get_node, bib_impact_query, bib_compute_communities, bib_coupling_report, etc.

Implementación

Núcleo: CreaRackVisitor, subclase ast.NodeVisitor que recorre AST y emite nodes y edges.

Tipos de nodo: module, class, model (hereda de Model), function, method.

Tipos de edge: contains (módulo→clase, clase→método), imports (relativos y absolutos), inherits, calls.

Detalles:

Zero deps: solo ast stdlib. Funciona en Python 3.10+ sin instalación.
Filtros de ruido: ignora imports bajo if TYPE_CHECKING: (solo tipo, no runtime) y lazy imports dentro de funciones. Ambos generaban falsos ciclos.
Cache SHA256: .bib_ast_cache.json en raíz. Modo --incremental salta archivos sin cambios.
Guard fallos silenciosos: parsea result.content[0].text, verifica errors[] y guard “0 created + 0 updated con payload no vacío”. Exit codes diferenciados (1/2/3). Surgió de incidente real: handler devolvía 200 con errors: ["D1 too many SQL variables"] y script lo consideraba éxito; grafo estancado semanas sin señal.

Decisiones

ast builtin, no libcst ni tree-sitter: cero dependencias, Python 3.10+. Precisión semántica de call edges limitada (resolución por nombre, no tipo), reflejado en campo confidence del edge.
App-by-app en cron: enviar una sola app activa replace_app en handler, que borra nodos obsoletos. Push de todo es aditivo pero no limpia fantasmas.
Exclusiones: migrations/, __pycache__, tests/, apps.py, admin.py. __init__.py incluido porque captura re-exports (from .x import Y).

Commits relacionados

2ff57af (2026-04-16) — commit raíz: feat: Biblioteca Graphify — AST extractor. Introduce scripts/bib_ast.py, handler bib_index_ast, 5 MCP tools.
v1.0.57 (2026-04-16) — CHANGELOG: 2212 nodos y 5951 edges primera extracción, 4 edge types, comunidades vía Label Propagation.
v1.0.58 (2026-04-17) — re-indexación 242s → 13s (18×) tras db.batch() + chunks; cron diario.
v1.0.58+ (2026-04-21) — migración cron Windows → Hetzner Staging (cron-bib-reindex.sh); guard errores silenciosos (Regla 15).

Véase también

[[concept—biblioteca—supercontexto]]