kedgeway

Documentación / Referencia / Fuentes de datos

Fuentes de datos

kedgeway no incluye una lista de versiones. En cada ejecución consulta al servidor MCP Stellar Raven (https://raven.stellar.org/mcp) con una sola llamada.

Qué consulta

FuentePara qué se usa
stellarDocs.get_doc_page sobre /docs/networks/software-versionsLa página oficial Software Versions: el soroban-sdk actual, el SDK de JavaScript actual y la versión del protocolo.
scout.analyzeEcosystem (toolchain)El índice de toolchains del ecosistema de Scout: una muestra de repos con versiones obsoletas de soroban-sdk.
stellarDocs.search_docsNotas de actualización y migración. Los cinco primeros resultados (título, URL y un fragmento corto) se guardan en el snapshot. diagnose no los imprime. migrate cita un resultado solo cuando su título o URL es un documento de migración.

Qué fuente tiene prioridad

  • La página oficial de documentación es la autoridad sobre qué es lo actual.
  • La lista de obsoletos de Scout es una muestra con un máximo de 50. Una entrada de Scout solo cuenta cuando está por debajo del major actual según la documentación.
  • Una dependencia con más de un major de atraso se considera obsoleta aunque Scout no la liste.

Procedencia en cada hallazgo

Cada hallazgo cita su fuente y la hora en que se observó. El encabezado del reporte muestra el major actual de soroban-sdk y la hora de observación, una marca de tiempo ISO 8601 en UTC tomada cuando la ejecución consultó a Raven.

DATA_DEGRADED

Si una fuente falla o devuelve algo que kedgeway no puede leer, la ejecución no se detiene y no adivina. Registra una nota, y cada nota se convierte en un hallazgo DATA_DEGRADED. Las notas nombran la fuente, por ejemplo:

  • stellarDocs.get_doc_page: <error>
  • software-versions: rust sdk row not found
  • scout.analyzeEcosystem: <error>
  • stellarDocs.search_docs: <error>

Cuando falta el major actual de soroban-sdk, los hallazgos del repo pasan a SDK_UNKNOWN y no se afirma que nada sea obsoleto.

Caché del snapshot

Después de cada consulta exitosa a Raven, kedgeway escribe el snapshot del ecosistema en $XDG_CACHE_HOME/kedgeway/snapshot.json (por defecto ~/.cache/kedgeway/, con modo de archivo 0600 y de carpeta 0700). Las ejecuciones siguientes lo reutilizan.

SituaciónQué pasa
Caché vigenteMás reciente que --max-age (por defecto 24h) y sin fecha en el futuro: se usa sin llamar a Raven.
Caché vencidaSe vuelve a consultar. Si Raven falla, se usa la caché vencida y un hallazgo DATA_DEGRADED dice using cached snapshot from <observedAt>.
--offlineNunca llama a Raven. Sale con 1 si no hay caché. Una caché vencida se usa con un hallazgo DATA_DEGRADED como snapshot is N hours old.
--no-cacheNo lee la caché ni usa el respaldo ante fallas, pero igual escribe el snapshot nuevo.
--max-age <duration>La antigüedad máxima de un snapshot en caché: 30s, 15m, 24h o 2d.
  • Un snapshot con notas DATA_DEGRADED nunca se escribe en la caché, y uno en caché que tenga notas cuenta como vencido.
  • --offline con --no-cache se rechaza (salida 1). --offline se ignora, con una advertencia, cuando se usa --fixture. --fixture omite la caché por completo.
  • La caché es un único archivo global. --max-age se aplica a su observedAt.