CreaRack-SL

Evaluación Understand-Anything vs Bibliotecario propio · NO adoptar, cherry-pick parcial

Vista limpiaEditar
ADRactivecreado Fri May 22#bibliotecario#supercontexto#evaluacion-herramientas#knowledge-graph#adr#claude-code-plugin

ADR 2026-05-22: Understand-Anything vs Bibliotecario — cherry-pick scope reducido

Contexto

El proyecto Understand-Anything propone 8 tipos de edges adicionales para enriquecer el grafo de conocimiento estático del Bibliotecario. La pregunta era: ¿importar el proyecto completo o hacer cherry-pick selectivo?

El análisis previo a esta decisión evaluó cada edge type propuesto frente a dos criterios:

  1. AST-friendly: detectable con parsing Python puro, sin dependencias externas.
  2. Valor inmediato: el Oráculo (bib_ask / bib_impact_query) puede usarlo en queries reales sobre el corpus de CreaRack Pro.

Decisión

Cherry-pick de 3 edge types (scope reducido) implementados directamente en scripts/bib_ast.py. No se incorpora Understand-Anything como dependencia ni submódulo.

Edge types incluidos

Edge typeMecanismo ASTJustificación
reads_from<Model>.objects.<READ>() en visit_CallDirecto, sin ambigüedad, alto valor para queries de impacto
writes_to<Model>.objects.<WRITE>() en visit_CallIdem, distingue lecturas de mutaciones
triggers@receiver(signal, sender=Model) en _visit_functionConecta signal handlers a sus modelos; útil para trazabilidad de efectos secundarios

Edge types descartados (en esta iteración)

Edge typeMotivo de descarte
subscribes / publishesRequieren parsers no-Python (Dockerfile, docker-compose, variables de entorno)
middlewareSensible a configuración runtime de Django; no inferible sólo del AST
deploysDominio de infraestructura, fuera del scope del AST Python
servesDepende de Django Channels o Huey — frameworks externos no siempre presentes

Los 5 tipos descartados quedan como candidatos para iteración futura si emergen necesidades concretas en queries del Oráculo.

Consecuencias

Positivas

  • +660 edges nuevos sobre corpus de 340 archivos (+10 % de enriquecimiento).
  • 0 falsos positivos detectados en muestra manual.
  • Riesgo bajo: solo añade edges, no modifica/elimina nodos ni edges existentes.
  • Sin nuevas dependencias en requirements.txt.
  • Si el cron falla, el grafo queda obsoleto, no corrupto.

Negativas / Limitaciones

  • Receivers de Django signals sin sender explícito no generan edge (señales globales no trazadas).
  • Los 5 edge types descartados siguen siendo puntos ciegos del grafo para infraestructura y mensajería.
  • La resolución de alias de import es best-effort: si _resolve_name no resuelve, el edge no se emite.

Implementación

  • Commit: 544548bbf243bcc48b546fcef435645938744e6d
  • Archivo: scripts/bib_ast.py — constantes ORM_READ_METHODS, ORM_WRITE_METHODS, SIGNAL_DECORATOR_NAMES + lógica en visit_Call y _visit_function.
  • Backup pre-cambio: /opt/biblioteca-crons-bak-20260522-pre-cherrypick/
  • Revert: git revert 544548b + rsync desde backup si el cron Hetzner falla.

Alternativas consideradas

  1. Importar Understand-Anything completo — descartado por scope excesivo, dependencias externas y riesgo de romper el pipeline existente.
  2. No hacer nada — descartado: el grafo carecía de trazabilidad ORM, lo que limitaba la utilidad de bib_impact_query para cambios en modelos.
  3. Implementar los 8 edge types — descartado: los 5 no-AST requieren parsers adicionales que elevan la complejidad de mantenimiento desproporcionadamente.

Estado

Aceptada — implementada en s79, 2026-05-22 · commit 544548b.

Véase también

  • [[entity—biblioteca—script—bib-ast]]

Referenciado desde

Inicio
Yo