El registro y el grafo fijado

Qué hace la etapa 1#

Un registro resuelve el grafo completo de paquetes y versiones de la aplicación y lo fija. Lee los metadatos de los proveedores con las credenciales configuradas del lado del servicio. No analiza código ni descarga ningún archivo. Un proveedor que no ofrece metadatos queda registrado como una excepción que requirió obtener un manifiesto.

La resolución maneja los peers con contextos explícitos, la política de dependencias opcionales y de compilación, los overrides y la reutilización opcional de un grafo anterior. Las entradas que no puede satisfacer producen un trabajo fallido con un motivo sobre el que se puede actuar, nunca un grafo fijado a medias.

Operaciones#

Crear un registro#

Los targets se leen de la aplicación tal como están cuando se acepta la solicitud. El cuerpo agrega qué más resolver; todos los miembros son opcionales:

Las credenciales de los proveedores privados nunca viajan en este documento. Una persona con el rol owner o admin las establece una vez para la organización; consulta Proveedores de registro.

La respuesta es 202 con el registro y su trabajo:

{
  "registration": { "id": "reg_a1B2c3D4", "state": "resolving", "job": "job_Reg00001x" },
  "job": { "id": "job_Reg00001x", "kind": "registration", "state": "queued" }
}

Un reintento con el mismo Idempotency-Key responde el mismo par. La admisión puede rechazar con QUOTA_EXCEEDED o BUDGET_EXHAUSTED.

Un registro está en resolving y luego en pinned, failed o cancelled. Una vez fijado lleva graph, el id de su grafo, y una instantánea de los targets que se resolvieron. Un registro fallido lleva failure, normalmente RESOLUTION_FAILED: una versión que no existe, restricciones en conflicto o un peer sin satisfacer. Sigue el trabajo como se describe en Trabajos.

Declarar imports dinámicos#

El rastreo estático no puede seguir un import() o un require() cuyo argumento no es un literal. declared le indica al análisis qué puede cargar un import así: por el especificador del módulo público que importa, los especificadores de los módulos públicos a los que puede llegar.

{ "declared": { "@acme/shop/main": ["@acme/ui/chart", "@acme/ui/table"] } }

El análisis sigue los módulos declarados como referencias de carga diferida e informa el import como DYNAMIC_IMPORT_DECLARED. Un import que queda sin declarar hace fallar la preparación con DYNAMIC_IMPORT_UNKNOWN. Una declaración agrega elementos al inventario y nunca cambia las entradas del módulo que importa, así que no invalida las salidas que ya existen. Cada lista contiene de 1 a 200 especificadores distintos.

Un manifiesto de módulo puede llevar la misma declaración. Este miembro es para los paquetes que no la llevan, como un paquete npm común que no puedes modificar.

El grafo#

graphs.read responde un resumen y el documento beyond-graph/1:

En el documento, los nodos tienen como clave su fuente y llevan el integrity, el tarball, el origin y la visibility del paquete: npm:<name>@<version> o <registry id>:<name>@<version> para una versión de un registro, git:<host>/<owner>/<repo>@<commit> para una fuente Git y digest:<algorithm>-<hex> para una URL de archivo comprimido. Un nodo leído con credencial registra además access, la evidencia de su visibilidad. Las aristas registran el tipo de dependencia, el rango pedido y el contexto de peer.

La resolución fija toda referencia mutable. Una rama o una etiqueta de Git pasa a ser el commit completo al que apunta; una URL de archivo comprimido sin fragmento de integridad se descarga una vez y se fija por su digest, registrado como una excepción del grafo. Las fuentes Git se leen por https desde github.com, gitlab.com, bitbucket.org y los hosts de esos tipos que declara el operador; cualquier otro host es UNSUPPORTED_INPUT. Dentro de una aplicación, un mismo name@version de dos fuentes, como una versión de un registro y un fork de Git que declara el mismo nombre y la misma versión, falla con UNSUPPORTED_INPUT. Un grafo que contiene un nodo leído con credencial tiene otro digest que el que daban las mismas entradas antes de que la visibilidad se registrara por paquete.

Revisa un cambio antes de prepararlo#

graphs.diff compara un grafo con un grafo base de la misma aplicación:

outputs es una predicción a partir de las claves de compatibilidad, informada aparte de los resultados medidos de compilación. Úsala para estimar el tamaño de un cambio, no para facturar ni para prometer tiempos de compilación.

Avisos de actualización#

Con notices habilitado en la aplicación, notices.list informa las actualizaciones de dependencias disponibles: el package, sus versiones current y available, y checked, la hora de la última consulta correcta al registro.

Un aviso informa. Nunca cambia una selección, prepara un release ni activa nada. Para adoptar una actualización, crea un registro nuevo, revisa la diferencia, prepara un candidato y pruébalo.

source: "unavailable" significa que no se pudo consultar el registro. Nunca es evidencia de que todo esté al día.