bib_impact_query — Tool CORE: impacto de cambios en dependencias y co-cambios

Descripción

bib_impact_query es una tool MCP CORE de la Biblioteca que, dado un archivo modificado, devuelve qué documentación y artefactos se verán afectados.

Combina dos señales:

1. Grafo estático (imports, calls, documentos enlazados) — dependencias declaradas.
2. Señal de co-cambio git (nuevo en PR#100, cherry-pick Cairn #2) — acoplamiento empírico.

Uso principal: antes de hacer un cambio substantivo, consultarla para identificar

• Archivos/modelos/endpoints dependientes.
• Documentación que necesita actualización.
• Archivos que suelen cambiar juntos (detección temprana de acoplamiento).

Firma

bib_impact_query(
  file_path?: string,
  model_name?: string,
  depth?: number = 2,
  min_confidence?: number = 0.0,
  cochange_min?: number = 2
) → ImpactResult

Parámetros

Una llamada típica:

{
  "file_path": "monitoring/api/signage.py",
  "depth": 2,
  "cochange_min": 2
}

Resultado (output)

{
  "start_nodes": 11,
  "direct_docs": [
    {
      "file_path": "src/content/wiki/entity--monitoring--model--signage-event.md",
      "kind": "entity_page",
      "references": 3
    }
  ],
  "related_endpoints": [
    "monitoring.api.v1:create_signage_event"
  ],
  "related_models": [
    "SignageEvent",
    "Device"
  ],
  "related_services": [
    "monitoring.services.signage_event_recorder",
    "monitoring.services.signage_state_manager"
  ],
  "cochanged_files": [
    {
      "file": "static/js/pages/signage/SignageContentManager.js",
      "count": 7,
      "last_seen": "2026-06-08T10:22:00Z"
    },
    {
      "file": "templates/signage_content.html",
      "count": 5,
      "last_seen": "2026-06-07T15:44:00Z"
    }
  ],
  "total_affected_nodes": 24,
  "total_edges_traversed": 38,
  "update_checklist": [
    "src/content/wiki/entity--monitoring--model--signage-event.md",
    "docs/api/signage.md"
  ]
}

Campos de salida

Acoplamiento estático vs. empírico

Grafo estático (BFS)

Detecta:

• Imports: from monitoring.models import SignageEvent → edge importa/exporta.
• Calls: función A llama función B → edge “calls”.
• Documentos: archivo X está en el update_checklist de modelo Y → edge “direct_docs”.

Ventaja: determinista, rápido, refleja intención del código. Limitación: invisible para cambios acoplados sin dependencias explícitas.

Señal de co-cambio git (nuevo)

Detecta:

• Acoplamiento implícito: monitoring/api/signage.py y static/js/pages/signage/SignageContentManager.js nunca se importan mutuamente, pero siempre cambian juntos → indica que pertenecen a la misma feature cross-capa.
• Patrones de dominio: cambios en un template y su API asociada.
• Efectos transversales: refactors que tocan múltiples capas simultáneamente.

Ventaja: basada en historicidad real, revela acoplamiento oculto. Limitación: requiere historial git suficiente; ruido si los archivos se modifican por motivos no relacionados.

Cómo se popula cochanged_files

1. Backfill one-shot (opcional, desde CreaRack-Pro/scripts/bib_cochange_backfill.py):

   • Lee el historial git completo.
   • Extrae pares de archivos que cambiaron juntos.
   • Invoca bib_record_cochanges con modo pairs para pre-cargar D1.

2. Post-merge ingest (incondicional, .github/scripts/bib_ingest.py):

   • En cada merge, extrae la lista de archivos tocados.
   • Invoca bib_record_cochanges con modo files.
   • El handler UPSERT los pares + incrementa count.

3. Degradación elegante:

   • Si la migración 0043 no se aplicó, bib_cochanges no existe.
   • La consulta es wrapped en try/catch → devuelve cochanged_files: [].
   • La tool jamás se rompe.

Casos de uso

1. Antes de un refactor

{"file_path": "monitoring/api/signage.py", "depth": 2}

→ “Voy a tocar este archivo. ¿Qué más se verá afectado?”

2. PR review

{"file_path": "forms/device_form.py", "cochange_min": 3}

→ “¿Qué otros archivos suelen cambiar con device_form.py?” → Resultado revela que un template HTML suele co-cambiar; el reviewer debe pedir que lo actualicen.

3. Impacto de bug fix

{"model_name": "Device", "depth": 3}

→ “Cambié el modelo Device. ¿Cuántos endpoints/servicios se rompen?”

Performance

• Consulta: O(E) donde E es el nº de aristas en el recorrido BFS (típicamente <100).
• Co-cambios: O(log N) en D1 gracias a índices en file_a y file_b.
• Timeout: <500ms típico (incluyendo hit a D1).

Integración con el ingest

Llamada automática desde bib_ingest.py tras cada PR mergeada:

# Opcionalmente, el ingest puede consultar bib_impact_query
# para auto-sugerir qué pages wiki crear o actualizar.
# (Feature futura; hoy es invocación manual de devs/reviewers.)

Evolución Cairn

Esta tool es el consumidor de la señal de co-cambio introducida en Cairn cherry-pick #2:

• Cherry-pick #1 (merged): anchors + confidence weights en bib_edges (grafo más fino).
• Cherry-pick #2 (este PR): bib_cochanges tabla + enriquecimiento en bib_impact_query.
• Cherry-pick #3 (ya en prod): supersesión de pages (una page puede estar superseded_by otra).

Véase también

• [[feature—biblioteca—cairn-cochanges]]
• [[entity—functions—service—bib-record-cochanges]]
• [[entity—functions—database—bib-cochanges]]
• [[concept—biblioteca—grafo-estatico-vs-empirico]]
• [[entity—functions—database—bib-edges]]