bib_cochange_backfill — Backfill de co-cambios git en bib_cochanges

Descripción

Script Python standalone (scripts/bib_cochange_backfill.py, 202 líneas) que rellena la tabla D1 bib_cochanges con datos históricos desde el inicio del repositorio git. Es un runbook one-shot: se ejecuta UNA sola vez tras desplegar la migración D1 0043 (que crea la tabla). No hay que volverlo a lanzar en operación normal — los merges futuros alimentan la tabla vía record_cochanges().

Cuándo ejecutar

• Momento: Inmediatamente después de desplegar la migración 0043 que crea bib_cochanges.
• Repo CreaRack-Pro: Desde el directorio raíz, con BIB_MCP_TOKEN en el env.
• Repo Workspace: Correr el script DENTRO del repo Workspace con --repo CreaRackSL-workspace.
• Frecuencia: Solo una vez. Re-ejecutar suma contadores de nuevo (no es limpio).

Uso

Dry-run (reporta sin publicar)

$env:BIB_MCP_TOKEN="<token>"  # PowerShell
python scripts/bib_cochange_backfill.py --dry-run

# Imprime los primeros 25 pares, ordenados por count descendente:
#   1234  monitoring/api/signage.py  ↔  static/js/pages/signage/SignageContentManager.js
#   ...
#   (+ N pares más)

Publicar de verdad

python scripts/bib_cochange_backfill.py
# [backfill] Leyendo historial git (repo=CreaRack-Pro, since=todo)…
# [backfill] 1250 commits no-merge con archivos.
# [backfill] 15432 pares distintos; 8912 con count>=2 (a publicar).
# [backfill] Lote 1: 500 pares.
# [backfill] Lote 2: 500 pares.
# ...
# [backfill] ✅ 8912 pares publicados en bib_cochanges (repo=CreaRack-Pro).

Opciones

# Limitar historial (ej: últimos 6 meses)
python scripts/bib_cochange_backfill.py --since "2025-12-09"

# Repo del Workspace (ejecutar dentro del directorio workspace)
python ../scripts/bib_cochange_backfill.py --repo CreaRackSL-workspace

Args completos:

• --dry-run — No publica; solo reporta pares agregados.
• --since <DATE> — Limita el historial git (ej: "2025-01-01"). Default: todo desde el inicio.
• --repo <REPO> — Etiqueta de repositorio. Default: CreaRack-Pro. Usa CreaRackSL-workspace para el Workspace.

Secretos (environment)

Obligatorio (salvo --dry-run):

• BIB_MCP_TOKEN — Bearer token del MCP Workspace. Ejemplo:

  $env:BIB_MCP_TOKEN="sk-proj-2024…"

Opcionales (si el MCP está tras Cloudflare Access):

• CF_ACCESS_CLIENT_ID — Cloudflare Access client ID.
• CF_ACCESS_CLIENT_SECRET — Cloudflare Access client secret.

Algoritmo

1. Lee historial git: git log --no-merges --name-only itera cada commit no-merge.
2. Filtra a código (mismas reglas que record_cochanges()):
   • Extiende .py, .ts, .tsx, .js, .jsx, .mjs, .cjs, .astro, .vue, .html, .css, .scss, .sql.
   • Excluye src/content/wiki/, .github/scripts/bib_*, scripts/harness/, public/supercontext/.
   • Excluye config/settings/base.py (alta rotación, ruido).
3. Cuenta pares: Para cada commit con 2–25 archivos de código, incrementa el contador de cada par (file_a, file_b) donde file_a < file_b.
   • Commits con >25 archivos se saltan (refactor masivo, señal débil).
4. Filtra por umbral: Solo publica pares con count >= 2 (1 = coincidencia casual).
5. Envía al MCP: Agrupa pares en lotes de ≤500 (límite del handler) y llama a bib_record_cochanges en modo pairs.

Parámetros anti-ruido:

MAX_FILES_PER_COMMIT = 25   # Commits que tocan >esto se saltan
BATCH_PAIRS = 500            # Pares por llamada MCP
CHURN_DENYLIST = ("config/settings/base.py",)  # Altísima rotación

Idempotencia

El script no es totalmente idempotente en el sentido de “re-ejecutar = mismo estado”:

• Si lanzas el backfill dos veces, la tabla bib_cochanges acumula contadores (suma de nuevo).
• Para una recarga limpia: vaciar bib_cochanges ANTES de ejecutar.

Esto es intencionado (la tabla se alimenta también en caliente vía record_cochanges() post-merge). Si necesitas reload:

-- En D1 (Workspace)
DELETE FROM bib_cochanges;
-- Luego ejecutar el backfill

Manejo de errores

• Red: Si BIB_MCP_TOKEN falta y no es --dry-run, termina con exit(1).
• MCP: Si el handler devuelve error, el script reporta y termina con exit(1).
• Git: Si git log falla, excepción no capturada (aviso intencional).

Fuentes

• Script: scripts/bib_cochange_backfill.py, 202 líneas.
• Docstring: Backfill de co-cambios git → bib_cochanges (Cairn cherry-pick #2 · s119).
• Migración D1: 0043 (crea tabla bib_cochanges).

Véase también

• [[feature—biblioteca—cochange-git]]
• [[entity—github-scripts—service—record-cochanges]]
• [[entity—supercontext—tool—bib-impact-query]]
• [[concept—biblioteca—logical-coupling]]
• [[decision—20260609—cairn-cherry-picks]]