Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

aggrega validate

aggrega validate comprueba la corrección — esquema, estructura de pilares, resolución de referencias entre documentos, cadenas extends, capacidad del provider respecto al tipo de entrada y (para una entidad que renderiza) que realmente renderiza. Tiene tres modos, seleccionados por su argumento, que aplican la misma disciplina de corrección a tres ámbitos: el catálogo completo (sin argumento), el cierre de dependencias de una única Release (--release) y el archivo de una entidad (una ruta de entidad). Cada ámbito responde a la misma pregunta — «¿es correcto este contenido?» — sobre una porción distinta del catálogo.

La corrección es distinta de las convenciones. aggrega validate pregunta si el contenido está bien formado y compilaría; aggrega lint pregunta si el contenido sigue la disciplina de publicación del catálogo (nomenclatura, alineación con el directorio de categoría, tamaño del incremento de versión y lo demás). Los dos comandos reflejan cada uno los tres ámbitos del otro, para que puedas comprobar cualquiera de las dos dimensiones con la granularidad que necesites.

aggrega validate no escribe nada en disco ni lee ningún estado de ejecución. Ejecuta la misma resolución y validación que ejecuta un build, deteniéndose antes del renderizado (o, para una sola entidad, aislándolo).

Se puede dar una ruta de entidad como argumento posicional. --release junto a una ruta de entidad no selecciona el ámbito de Release: la entidad se sigue comprobando por sí sola, en los términos de esa Release — consulta Comprobar una entidad en los términos de una Release.

Corrección de todo el catálogo (sin argumento)

aggrega validate sin argumento carga cada entidad de catálogo bajo los directorios de catálogo configurados y la comprueba de principio a fin. Antes de cargar nada, lee cada archivo YAML que hay en ellos, y un documento de Aggrega entre ellos que no puede cargar detiene la ejecución, como se describe más abajo. Después:

  • Estructura de los pilares del esquema: el bloque spec.schema: de cada Component y de cada Feature se expande y se valida (la misma comprobación de pilares del esquema que aplica la compilación), incluida la expansión de la forma compacta.
  • Resolución de referencias entre documentos: las referencias $ref y $import a entradas de una SchemaLibrary se resuelven, y una SchemaLibrary que no se puede resolver o que es inválida por otro motivo se rechaza.
  • Cadenas extends — cada entidad que declara extends se resuelve frente a su padre, y se comprueba la forma combinada padre+hijo. Un padre que los directorios de catálogo no contienen se lee donde lo lee una compilación: desde la caché de artefactos, según la fijación que el lockfile de una Release registra para él — los lockfiles de las Releases para las que se ejecuta la pasada, o de cada Release que contiene el espacio de trabajo cuando este se valida en una sola pasada. Así, una base publicada en un registro se valida una vez que aggrega pull la ha obtenido y fijado, y un padre que ninguno de los dos contiene detiene la ejecución, nombrando aggrega pull --release <release>. No se obtiene nada.
  • Selectores declarados — cada selector de etiquetas que un documento Component o Feature declara en un socket de dependencia bajo spec.usesSchema, o en un slot de adjunto bajo spec.featuresSchema — incluidos, en un Component, los slots que declara un socket — se lee contra la gramática de selectores, tanto si algo cablea el socket o rellena el slot como si no. Consulta selectores declarados.
  • Colisiones de ubicación OCI: dos identidades de catálogo distintas que publicarían en la misma ubicación del registry se rechazan de forma explícita, de modo que una compilación nunca sobrescribe en silencio los bytes publicados de una entidad con los de otra.
  • Capacidad de tipo de entrada del Provider — una Recipe o una FeatureRecipe que declara un bloque workload: vinculado a un provider que no puede sintetizar se marca como error, porque nunca puede compilarse.

Esta es la contraparte, para todo el catálogo, de la validación por Release de una compilación: el lugar donde debe aflorar una entidad de catálogo defectuosa, antes de que una Release la alcance. Se detiene de forma explícita ante un documento de Aggrega que no puede cargar, y ante cualquier violación de los pilares del esquema, biblioteca irresoluble o inválida, fallo de resolución de extends, selector declarado que la gramática rechaza, colisión de ubicación o error de capacidad según el tipo de entrada. Los hallazgos de solapamiento de pilares del esquema y de estrechamiento al extender, y cada palabra clave x-aggrega-* que un Component o una Feature escribe en línea en el contenido de su esquema, son líneas notice: informativas que nunca cambian el código de salida.

Un documento de Aggrega que no se puede cargar detiene la ejecución. Un archivo YAML bajo un directorio de catálogo es un documento de Aggrega cuando una de sus líneas empieza, sin sangría, por apiVersion: y un valor que comienza por aggrega.ai/, entre comillas o no. Uno que no se puede leer, cuyo YAML no se puede analizar, o cuyo kind o metadata no tiene la forma que adopta el sobre de una entidad —un metadata escrito como lista, por ejemplo— detiene la ejecución con E0175 una vez leídos los directorios, nombrando cada uno de esos archivos con el motivo que dio la lectura o el analizador; no se comprueba nada y no se imprime ninguna línea catalog validation passed. Uno que se carga y declara un kind que ningún catálogo contiene —un Componnent mal escrito, por ejemplo, o ningún kind— detiene la misma ejecución con E0371, y se nombra junto a ellos con el tipo que declara; un Manifest, una Release y un Workload que una Recipe importa desde su propio directorio se omiten. Cualquier otro YAML —las plantillas de un chart de Helm, que no se pueden analizar hasta que se renderizan, los valores de un chart, las definiciones de flujos de trabajo— se omite.

Los directorios que lee dependen de la forma del workspace:

  • Un workspace cuya configuración no asigna a ninguna Release directorios de catálogo propios se valida una sola vez, sobre su pila de búsqueda: los directorios --catalog, luego workspace.catalog_dirs y luego el directorio catalog en la raíz del workspace cuando existe.

  • Un workspace que nombra Releases en workspace.releases puede mantener un catálogo en varias variantes una junto a otra, cada una leída por su propia Release, y cargarlas todas a la vez pondría cada variante en un único catálogo, con la entidad de una variante ocultando la de otra. Por eso se valida una vez por cada Release que contiene el workspace, sobre los directorios que lee esa Release, con los directorios --catalog primero en cada pasada; una Release que la configuración no nombra lee la lista del workspace. Cada pasada se informa bajo una línea que nombra su Release y los directorios que leyó, seguida del resultado de esa pasada:

    Release release-compose.yaml reads catalog-compose
    catalog validation passed (schema-pillar + library + extends + oci-location)
    Release release-helm-synth.yaml reads catalog-helm-synth
    catalog validation passed (schema-pillar + library + extends + oci-location)

    Las Releases que leen exactamente los mismos directorios comparten una pasada, que nombra a cada una de ellas. Una Release que no lee ningún directorio —su entrada escribe catalog_dirs: []— se informa como sin nada que comprobar, y las demás pasadas se ejecutan con normalidad. Cada pasada se informa sea lo que sea lo que haya encontrado una anterior, ya que una entidad defectuosa en una variante no dice nada de otra, y el comando falla cuando falla cualquier pasada, nombrando las Releases cuyos directorios fallaron. Las Releases que contiene un workspace son sus documentos Release: archivos YAML cuyo kind es Release, en cualquier lugar bajo la raíz del workspace fuera de los directorios ocultos y de node_modules, vendor y dist.

Una ejecución sin nada que leer en ninguna pasada se rechaza en lugar de informarse como un catálogo limpio: pon las entidades en catalog/, pasa --catalog o define workspace.catalog_dirs —o, en un workspace que nombra Releases, los catalog_dirs propios de una Release en workspace.releases—. Nunca enumera implícitamente el directorio de trabajo actual, por lo que nunca incorpora árboles ajenos.

La herramienta validate de aggrega mcp, cuando se le pide todo el catálogo, valida las mismas pasadas; en un workspace que nombra Releases, su respuesta incluye cada una en passes —las Releases, los directorios leídos y el veredicto propio de esa pasada— junto al veredicto sobre todas ellas.

Una biblioteca que solo contiene la caché de artefactos

La caché de artefactos contiene lo que una descarga dejó en ella, y una SchemaLibrary en caché cuenta como contenido de catálogo solo donde una entrada del lockfile de una Release avala su digest; consulta Qué es la caché y qué no es. Cuando un $ref: no se resuelve en nada mientras la caché contiene una biblioteca que ninguna entrada de lockfile fija y que ningún directorio de catálogo leído por la comprobación aporta, el informe va seguido de una línea remediation: que nombra cada una de esas bibliotecas y la acción que funciona para el ámbito que falló:

  • Sin argumentos, y con una ruta de entidad, se indique o no --release, validate lee las bibliotecas solo de los directorios de catálogo, nunca a través de una entrada de lockfile, por lo que una entrada registrada no cambiaría su veredicto. La línea lo dice y remite a escribir la biblioteca bajo un directorio de catálogo, o a aggrega pull --release <release> seguido de aggrega validate --release <release>, que comprueba la Release frente a las bibliotecas que fija su lockfile.
  • Con --release solo, validate lee el lockfile de la Release, así que la línea nombra aggrega pull --release <release>, que resuelve la biblioteca y registra su entrada, o la escritura de la biblioteca bajo un directorio de catálogo.

La línea no cambia ni el veredicto ni el código de salida.

Selectores declarados

Un Component o una Feature restringe lo que puede cablearse a sus sockets de dependencia, y lo que puede rellenar sus slots de adjunto, con selectores de etiquetas — el selector: de cada entrada de spec.usesSchema y de cada entrada de spec.featuresSchema, y en un Component el selector: de cada slot que un socket declara bajo su propio featuresSchema. Una compilación lee un selector solo donde algo lo alcanza: una arista trazada a través del socket, un adjunto que rellena el slot. Por eso el ámbito de todo el catálogo y el ámbito de una sola entidad leen cada selector que declara un documento Component o Feature, tanto si algo cablea el socket o rellena el slot como si no, y un selector que la gramática rechaza — una lista de valores a la que le falta el paréntesis de cierre, una coma duplicada, una clave que lleva = o ! — hace fallar la comprobación. La gramática es la que se explica en la gramática de cadenas.

El rechazo es el que informa una compilación cuando alcanza el mismo selector, con el mismo código y en las mismas palabras: E0007 para el selector de un socket y E0008 para el de un slot, nombrando el selector, el socket o slot que lo declara y por qué la gramática no pudo leerlo. Se registra como fallo del catálogo en el archivo de la entidad:

selector violation ("<selector>", declared on socket "<socket>", which could not be evaluated: "<why it could not be read>"). Correct the selector on the socket’s declaration in the component type’s usesSchema. (infracción de selector: selector declarado en un socket que no se pudo evaluar. Corrige el selector en la declaración del socket, en el usesSchema del tipo de componente.)

Cada documento se lee tal como lo escribió su autor, así que un selector que declara una entidad base se informa una sola vez, en el propio archivo de la base, en lugar de una vez por cada entidad que la extiende. Los appliesTo y appliesToAnyOf de una Feature no se leen aquí: se leen dondequiera que se evalúa un adjunto de la Feature.

El ámbito de todo el catálogo informa cada selector rechazado en su propia línea selector: y falla indicando cuántos son; el ámbito de una sola entidad los informa como fallo de su nivel de forma — con o sin --release junto a la ruta de la entidad, ya que esa forma es el ámbito de una sola entidad ejecutado en los términos de una Release (consulta comprobar una entidad en los términos de una Release). --release solo, que valida el cierre de dependencias de una Release, y una compilación leen un selector solo donde lo alcanza una arista o un relleno, y se detienen allí en él.

Corrección limitada a una Release (--release)

aggrega validate --release <release-path> valida exactamente las entidades que alcanzan las dependencias resueltas de una sola Release, en lugar de todo el catálogo o una sola entidad. Calcula el cierre mediante la misma maquinaria que usa una compilación, de modo que las entidades que comprueba son exactamente las que resolvería una compilación de esa Release, y sobre ese cierre:

  • resuelve las cadenas extends limitadas al cierre, y falla ante un error de resolución;
  • valida los pilares del esquema de cada entidad resuelta (limitados al cierre), y falla ante un error de pilares del esquema;
  • ejecuta la misma comprobación de conformidad de valores previa al renderizado que ejecuta una compilación: resuelve los parámetros de la Release en los valores escritos por el autor (así un valor {{ .parameters.* }} se comprueba ya resuelto, no como plantilla) y valida el resultado contra los esquemas compuestos del cierre, incluida la conformidad con el esquema compuesto padre+hijo para una entidad que usa extends. Un valor que viola su esquema falla con un código de salida distinto de cero;
  • evalúa cada aserción de Recipe y FeatureRecipe frente a los valores en los que se resuelve la Release, igual que una compilación las evalúa antes de renderizar: la Recipe de cada componente se vincula tal como la asigna el Manifest, se resuelven sus locals y provides, y la primera aserción que falla —una que llama a fail, o una cuya plantilla se detiene en una clave que no encuentra— hace fallar la validación con la condición y la frase con las que se detiene una compilación. Una plantilla locals o provides que no se puede evaluar también la hace fallar, igual que hace fallar una compilación. Al provider a través del cual renderiza cada Recipe se le pide el nombre que da a los recursos de ese componente, igual que se lo pide una compilación, porque los provides de una Recipe pueden leer ese nombre; no se renderiza nada. Estas aserciones solo se evalúan cuando nada de lo anterior ha fallado ya, de modo que una Release informa del primer fallo en el que se detendría una compilación;
  • muestra los hallazgos de solapamiento de pilares del esquema y de estrechamiento al extender como líneas notice: informativas que nunca cambian el código de salida;
  • muestra cada palabra clave x-aggrega-* que una entidad que lee escribe en línea en el contenido de su esquema como una línea warning:, una vez por entidad, igual que la muestra una compilación; tampoco cambia nunca el código de salida.

Esto convierte --release en una verdadera comprobación previa a la compilación: detecta lo que una compilación rechazaría, antes de la compilación; es la validación de dependencias de la compilación sin el renderizado. No renderiza nada ni desencadena ningún pull de red: el cierre se resuelve desde el catálogo local (y desde los pines del lockfile de la Release, si existe); un conjunto de dependencias fijadas a un registry que necesita un lockfile muestra un error honesto de referencia irresoluble en lugar de descargar. El estrechamiento se muestra como consejo, nunca se impone.

Un lockfile que ya no coincide con aquello a lo que se resuelve la Release hace que se rechace la validación con la detención que imprime aggrega build. Cuando hay un lockfile junto a la Release, --release lo contrasta con aquello a lo que se resuelve la Release, con la comparación de deriva que ejecuta una compilación antes de renderizar, en cuanto se resuelven las dependencias de la Release y antes de que se ejecute cualquiera de las comprobaciones anteriores. Un lockfile del que se ha desviado una entidad fijada, una biblioteca, un plugin o el propio archivo de la Release detiene la validación con el rechazo E0130 de la compilación — cada entrada que se desvió y, después, el aggrega pull --release <release> que lo soluciona — y un código de salida distinto de cero, de modo que una validación nunca deja pasar un lockfile que la compilación rechaza por deriva. Sin argumento, y con una ruta de entidad, validate no está sujeto a ningún lockfile: la comprobación de todo el catálogo lee las fijaciones del lockfile solo para encontrar un padre de extends, y la comprobación de una sola entidad no lee ningún lockfile.

Como ejecuta las mismas comprobaciones que una compilación, también ejecuta los mismos plugins de control adjuntos, de modo que está sujeto al mismo registro de identidades de plugins de confianza al que está sujeta una compilación. Un workspace que adjunta un plugin que devuelve un veredicto de aceptación o rechazo tiene un registro de confianza de plugins junto a su Release, y --release compara la configuración con él antes de que se ejecute cualquiera de esos plugins: un control registrado que la configuración ya no adjunta detiene la validación, y un plugin resuelto desde la caché que llena aggrega pull cuyo artefacto no es el registrado se rechaza en lugar de ejecutarse. Un workspace que no ha registrado nada no tiene registro, lo que no cambia nada para esa comparación. --release también nombra cada retirada registrada contra aquello de lo que depende la Release, en la salida de error estándar, como una línea deprecation: con las palabras que imprime aggrega build: tanto una marca que el lockfile registra contra una referencia fijada como una que el registro de confianza registra contra un plugin adjunto en un rol de veredicto. Una retirada no cambia ni el veredicto ni el código de salida, y un registro de confianza que existe y no se puede leer detiene la validación en lugar de pasar por uno que no registra nada.

Un plugin leído desde la caché también está sujeto a la firma que registra su entrada, igual que lo sujeta una compilación, en el momento en que se carga. Donde su entrada registra una firma verificada, el material de firma que ese hecho nombra en la caché se vuelve a comprobar, y un plugin cuyo material falta o difiere se rechaza, al igual que uno cuyo material se creó para un plugin distinto del leído, que es el aspecto que tiene una signature copiada de otra entrada, diga lo que diga el requisito de firma. Donde la configuración de confianza del workspace exige una firma, un plugin leído desde la caché cuya entrada no registra ninguna —o para el que el registro no contiene ninguna entrada, incluido un registro eliminado— también se rechaza, con los mismos ajustes que harían que aggrega pull lo rechazara sin firmar, de modo que skip_signature_verification y un registry advisory permiten que se ejecute. Un rechazo hace fallar la validación y se informa entre sus diagnósticos, nombrando el plugin y aggrega pull --release <release>, el comando que verifica su firma en su registry, la registra y guarda en caché el bundle que nombra, reescribiendo una copia en caché que ya no coincide con su digest; un plugin servido desde uno de tus directorios de catálogo, o desde la copia incluida en el binario del compilador, nunca está sujeto al requisito. Los otros dos ámbitos no están sujetos a nada de esto: no leen los adjuntos de plugins del workspace, por lo que en ellos no se ejecuta ningún plugin de ese tipo.

Lo mismo ocurre con los plugins que cambian el grafo en lugar de juzgarlo. Un adjunto label-transform o annotation-transform da forma a lo que sería la salida renderizada, por lo que el lockfile fija tanto su identidad como los archivos fuente que lee, y --release ejecuta esos adjuntos como los ejecuta una compilación: reconstruidos a partir del lockfile, sujetando cada uno a su digest registrado y leyendo el contenido fuente que lleva el lockfile en lugar del archivo en disco. Conviene conocer dos consecuencias antes de encontrarlas:

  • Adjuntar un plugin de transformación en .aggrega-config.yaml no cambia lo que hace --release hasta que ejecutes un pull. Es la misma regla que sigue una compilación, y por la misma razón: el conjunto de adjuntos es una entrada que determina los bytes, por lo que se adopta en el pull y no en el momento en que se edita.
  • Un plugin en caché cuyos bytes ya no coinciden con el digest que registró el lockfile se rechaza, exactamente como ocurriría durante una compilación.

Si la Release no tiene lockfile, --release valida igualmente: advierte de que no pudo comprobar la identidad de un plugin e indica qué ejecutar, en lugar de rechazar. Consulta advertencias.

Devolver el grafo compilado

--ir-graph escribe en la salida estándar, como JSON, el grafo que resolvió esta validación, antes de la línea del veredicto. Es aditivo: se ejecutan las mismas comprobaciones, se escriben los mismos diagnósticos y el código de salida es el mismo que sin él. El grafo devuelto es aquel sobre el que se realizó la validación, por lo que no puede describir una resolución distinta de aquella sobre la que informa el veredicto.

Se aplica solo a este ámbito —los ámbitos de todo el catálogo y de una sola entidad usan un arnés sintetizado en lugar de una Release, y no resuelven ningún grafo— y pedirlo en otro lugar se rechaza en lugar de ignorarse en silencio. Si la ejecución se detiene antes de que se resuelva el grafo, no se escribe nada en la salida estándar y los propios diagnósticos del comando indican qué la detuvo.

Fíjate en la opción contigua. --response-format establece cuánto del propio informe de este comando se escribe (detailed o concise); --ir-graph pide un segundo documento junto a ese informe. Una es volumen, la otra es tema, y ninguna cambia el veredicto.

Los valores que un autor declaró sensibles se retienen del grafo —incluidos los values y el infra de una conexión, donde el socket del componente consumidor declara sensible una hoja—, en la forma estructurada descrita en aggrega inspect. --unredacted junto a --ir-graph los imprime en su lugar, en los términos que establece aggrega inspect --unredacted: alcanza el grafo y nada más de lo que escribe este comando, y cualquier destino al que llegue la salida contiene entonces esos valores en claro. Pasado sin --ir-graph se rechaza, porque no habría nada que revelar.

Corrección de una sola entidad (una ruta de entidad)

aggrega validate <entity-path> comprueba un único archivo de entidad de catálogo. Aplica un conjunto escalonado de comprobaciones y se detiene en el primer fallo bloqueante, de modo que un error de esquema aflore de forma explícita antes de cualquier trabajo sobre el catálogo:

  • Marcadores de posición (todo tipo): un valor que el tipo exige y que el archivo deja como cadena vacía. Se informan todos a la vez, antes de las demás comprobaciones, cada uno con lo que admite; consulta marcadores de posición aún pendientes.
  • Sobre del esquema (todo tipo): la comprobación exacta de JSON-Schema por entidad que ejecuta el cargador del catálogo en cada frontera de análisis.
  • Forma (cualquier tipo) — la validación estructural específica del tipo. Para un Component o una Feature incluye leer cada selector de etiquetas que el archivo declara en un socket de dependencia o en un slot de adjunto contra la gramática de selectores; consulta selectores declarados.
  • Estructura de pilares (Component y Feature): la comprobación de pilares spec.schema:, que usa las SchemaLibraries del catálogo para la expansión de $ref entre documentos.

Un Component o una Feature se detiene ahí: sobre del esquema, forma y estructura de pilares. Un Component aislado no tiene values ni infra escritos por el autor que renderizar de forma aislada, así que no hay nada que renderizar: su corrección queda totalmente cubierta por los niveles de esquema y pilares. Cada palabra clave x-aggrega-* que el contenido de su esquema escribe en línea se informa entre las notas informativas de la salida de error estándar como una línea warning: que nombra la palabra clave, dónde está y la tabla declarativa que escribir en su lugar; nunca cambia el veredicto ni el código de salida.

Una Recipe además se renderiza de forma aislada. Esta es una faceta de la corrección de una sola entidad, no su aspecto principal: una vez superados los niveles de esquema y forma, validate resuelve desde el catálogo el Component de implements de la Recipe, sintetiza un Aggregate, un Manifest y una Release mínimos en torno a una única instancia de ese Component vinculada a la Recipe que se prueba, y ejecuta sobre ellos la verdadera canalización de compilación: primero la resolución y las guardas (con el renderizado omitido) y después un renderizado real de la salida aislada. Cada valor obligatorio y cada campo infra obligatorio sin valor por defecto se rellena con un marcador de posición de su tipo declarado —los valores en el Aggregate sintetizado, la infra en la Release sintetizada— y cada otro valor y campo infra toma su valor por defecto del esquema a través del resolvedor; la Release encamina la instancia a un boundary por defecto sintetizado y no declara ningún values: ni ningún recurso de cómputo que el Aggregate no haya declarado. Un marcador de posición es un valor que aceptan las restricciones declaradas del propio campo: la constante o el primer valor que enumera un enum, un número dentro de sus límites, una cadena de su longitud y en su format, una versión semántica donde su pattern pide una, tantos elementos de lista como exige, y cada propiedad que exige un objeto. Cualquier otro pattern, una condición validate: o when:, una composición de esquemas y una restricción sobre qué elementos contiene una lista no se consultan, por lo que un campo que dependa de uno de ellos puede rechazar igualmente su marcador de posición; validate informa entonces de ese rechazo con las propias palabras del esquema. Los artefactos renderizados se imprimen para que el autor vea la salida aislada antes de conectar la entidad a un Aggregate completo. Como un arnés de una sola entidad rellena solo esos campos obligatorios, no conecta ninguna conexión y no adjunta ninguna Feature, una Recipe cuyas plantillas leen un valor que solo proporciona una conexión o una Feature adjunta no puede renderizarse de forma aislada; validate informa de ese renderizado como no intentado en lugar de fallido. Una aserción que llama a fail se informa como advertencia en lugar de hacer fallar la comprobación; consulta una aserción fallida es una advertencia. Un renderizado que se detiene por cualquier otro motivo no se completó, y validate lo informa con el diagnóstico de renderizado subyacente hasta la frase que nombra lo que lo detuvo.

Una Recipe cuyo source: tiene que descargarse no se renderiza en absoluto, y una Recipe cuyo renderizado se detiene mientras lee un valor que solo proporciona una conexión o una Feature adjunta ve ese renderizado apartado; consulta qué no comprueba la corrección de una sola entidad más abajo.

Una FeatureRecipe se comprueba en esquema y forma; su renderizado se omite, porque una FeatureRecipe solo se renderiza cuando está adjunta a un componente anfitrión, y no se intenta sintetizar un anfitrión que supere las guardas para una Feature arbitraria.

Comprobar una entidad en los términos de una Release

Un workspace puede asignar a cada Release directorios de catálogo propios —consulta Asignar a una Release sus propios directorios de catálogo— y así mantener una variante de catálogo por Release una junto a otra. Una ruta de entidad indicada sola se comprueba sobre los propios directorios de catálogo del workspace, donde una referencia a una de esas variantes —el Component que implementa una Recipe, una SchemaLibrary a la que remite un pilar— no se encuentra. Indica --release junto a la ruta de entidad y las mismas comprobaciones se ejecutan en los términos de esa Release: las referencias de la entidad se resuelven a través de los directorios de catálogo que la configuración del workspace asigna a esa Release, con cualquier --catalog antepuesto, que son los directorios que lee una compilación de esa Release.

El ejemplo MariaDB + Adminer mantiene cuatro variantes de este tipo. El Component de su variante synth toma su configuración de almacenamiento de una SchemaLibrary que solo contienen las variantes synth y chart, por lo que se valida en los términos de la Release que compila con él:

$ aggrega validate catalog-helm-synth/component/mariadb.yaml --release release-helm-synth.yaml
Entity: catalog-helm-synth/component/mariadb.yaml
Kind: Component
Schema: valid
Pillars: valid

y falla, nombrando la biblioteca que no pudo resolver, en los términos de una Release cuyos directorios no la contienen: --release release-compose.yaml, o ningún --release en un workspace que no enumera directorios de catálogo propios.

Una Recipe se comprueba del mismo modo. La Recipe de la variante synth implementa core/datastore/mariadb, que los propios directorios de catálogo del workspace no contienen, así que indicada sola falla con render: implements target "core/datastore/mariadb" not found in catalog. Indicando la Release que compila con ella, resuelve el Component de esa Release y se renderiza de forma aislada:

$ aggrega validate catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml --release release-helm-synth.yaml
Entity: catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.
Resolution: valid
Render: 3 artifact(s)

seguido de los tres artefactos renderizados. Cada variante de ese ejemplo declara core/datastore/mariadb, por lo que la Recipe se valida en los términos de cada una de sus cuatro Releases; en los términos de una Release cuyos directorios de catálogo no contienen tal Component, falla nombrando el destino, como ocurre sin --release. Las líneas Attachments: se explican en una ranura de adjunto obligatoria o un mandato de presencia.

Sigue siendo el ámbito de una sola entidad. Las comprobaciones, el informe y el código de salida son los que describe esta sección — un Component o una Feature que lleva un selector de socket o de slot que la gramática rechaza falla aquí exactamente igual que sin --release, consulta selectores declarados — y no se valida ningún cierre: --release nombra la Release a través de cuyos directorios de catálogo se leen las referencias de la entidad, no un cierre que comprobar, y por eso --ir-graph se rechaza junto a una ruta de entidad. Un --release que nombra un archivo que no existe, o un directorio, se rechaza antes de comprobar nada.

Un directorio que la configuración del workspace enumera y que no es un directorio —porque no existe nada allí, por ejemplo—, para esa Release, o para el workspace cuando no se indica --release, se rechaza antes de comprobar nada, igual que lo rechaza cada comando que lee ese catálogo (De dónde se leen las entidades locales): el rechazo nombra la entrada, el archivo de configuración y la línea que la enumeran, y el ajuste, y no se da ningún veredicto. La comprobación de entidades del editor a través de aggrega serve da el mismo rechazo como única entrada sobre el archivo de la entidad, en el nivel de error, y la herramienta validate de aggrega mcp rechaza la llamada con él.

Marcadores de posición aún pendientes

Un valor que el tipo exige y que el archivo deja como cadena vacía es un marcador de posición, y validate lo informa antes que cualquier otra cosa. Un documento esbozado por aggrega scaffold lleva uno dondequiera que su tipo necesite un valor que solo tú puedes proporcionar, así que aquí es donde descubres cuáles quedan. Esta es una FeatureRecipe esbozada con solo la versión rellenada:

Entity: my-feature-recipe.yaml
Kind: FeatureRecipe
2 placeholders still owed in my-feature-recipe.yaml; an empty required value is not a value, so each of these needs one before the document validates:
7:3: spec.capability takes what its schema describes: The explicit provider capability this recipe binds to (e.g., 'helm', 'terraform', 'compose') — the provider kind that renders it.
8:3: spec.implements takes what its schema describes: Declares which catalog Feature type this recipe is able to implement (including credential Features labeled feature.aggrega.ai/kind: secret; exact version, major-compatible range '^', or unversioned).

Todos los marcadores de posición del archivo se nombran a la vez, en el orden del documento, con su línea y columna y con lo que admiten. Lo que admiten se lee del propio esquema del tipo: los valores que acepta donde el esquema los enumera, una versión semántica como 1.0.0 donde el esquema pide una, y en otro caso la primera frase de la propia descripción del campo en el esquema.

Qué valores cuentan también se lee del esquema. Un valor cuenta cuando el tipo lo exige en el nivel superior del documento, o dentro de un objeto que el tipo también exige, y el archivo lo establece como cadena vacía. Una clave que el archivo omite por completo la informa la comprobación del esquema como propiedad ausente. Un campo opcional dejado vacío no es un marcador de posición, ni tampoco un campo obligatorio solo dentro de una lista o un mapa que elegiste escribir. Donde el propio esquema enumera la cadena vacía entre los valores que acepta un campo, una vacía es un valor y no un marcador de posición.

Un valor está pendiente aunque el esquema lo aceptaría vacío. El esquema admite una cadena vacía para capability e implements de una Recipe o FeatureRecipe, pero una vacía no nombra ningún provider ni ningún tipo, así que validate informa de ambos como marcadores de posición como cualquier otro. Donde la comprobación del esquema también rechaza el mismo archivo —una versión vacía, una etiqueta de tipo sin valor—, el informe lleva el código de esa comprobación, E0215, como muestra el ejemplo en aggrega scaffold; donde la comprobación del esquema lo acepta, como arriba, el informe no lleva código. Un hallazgo en el mismo archivo que no trata de un valor vacío se informa igualmente, con las propias palabras de la comprobación del esquema, antes de la lista.

Esta lectura pertenece a la validación de una sola entidad, con o sin --release junto a la ruta de entidad. Una ejecución de todo el catálogo que encuentra el mismo documento informa de lo que informa la comprobación del esquema, de modo que una FeatureRecipe con un implements vacío dentro de un directorio de catálogo la supera; el ámbito de Release y aggrega build tampoco aplican esta lectura.

Un tipo que este ámbito no admite

La validación de una sola entidad admite Component, Feature, Recipe, FeatureRecipe, Workload y Plugin. Un archivo de cualquier otro tipo se rechaza, y el rechazo nombra los tipos que admite y, para un tipo de entidad, el ámbito que sí comprueba un documento de ese tipo:

kind "Aggregate" in "aggregate.yaml" is not a single-entity validation target; the kinds this scope accepts are Component, Feature, Recipe, FeatureRecipe, Workload and Plugin. An Aggregate is checked by the whole-catalog scope when it sits in a catalog directory, and by the Release scope over a Release that deploys it

El ámbito de todo el catálogo es una ejecución sin argumento, y el ámbito de Release es --release sin ruta de entidad:

TipoComprobado por
Aggregateuna ejecución de todo el catálogo, cuando está en un directorio de catálogo; --release sobre una Release que lo despliega
Manifest--release sobre una Release que lo nombra
Release--release <release-path>
SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibraryuna ejecución de todo el catálogo, cuando está en un directorio de catálogo

Una ejecución de todo el catálogo lee solo lo que está dentro de los directorios de catálogo configurados, por lo que un Aggregate guardado en la raíz del workspace junto a su Release se comprueba mediante --release sobre esa Release.

Una aserción fallida es una advertencia

Una aserción que llama a fail —una que declara la Recipe, o una que declara su Component de implements— se informa como advertencia, y la comprobación no falla por ella. La Release sintetizada lleva marcadores de posición y valores por defecto del esquema en lugar de los valores que establece una Release real, por lo que una aserción sobre uno de esos valores, una imagen o la presencia de un requisito previo, falla aquí tanto si la Recipe es correcta como si no, y validate no puede distinguir una aserción que espera a una Release de una que está rota. El veredicto sobre la aserción se deja a una compilación, que siempre tiene una Release.

La advertencia se escribe en la salida de error estándar, encabezada por warning:, después de cualquier nota informativa. Lleva el mensaje completo de la aserción —la entidad, la instancia, el nombre de la aserción y la frase que escribió su autor— cerrado por una frase más:

A Release must satisfy this assertion before a build of it can pass.

El informe en la salida estándar indica dónde se detuvo la ejecución, y el comando termina con 0. La propia aserción de una Recipe detiene el renderizado, así que el informe dice Render: stopped on a failed assertion, reported as a warning después de Resolution: valid. La aserción de un Component se evalúa antes de renderizar nada, así que el informe dice Resolution: stopped on a failed assertion, reported as a warning, seguido de Render: not attempted (the run stopped on that assertion). En ambos casos no se renderiza nada, por lo que no se imprime ningún artefacto.

Solo una aserción que llama a fail es una advertencia. Una aserción que se detiene en una clave que lee pero no encuentra, o que no se puede analizar, es un fallo en el propio texto de la aserción y no una aserción fallida, y se juzga como cualquier otra detención. Cualquier otro fallo conserva su lugar como veredicto de la comprobación.

aggrega build de una Release que no satisface la aserción se detiene en ella con un error, nombrando la aserción e incluyendo la frase de su autor, como siempre, y aggrega validate --release sobre esa Release falla en ella con el mismo error. La comprobación de entidades del editor a través de aggrega serve da la misma advertencia, dibujada sobre la propia clave de la aserción donde la Recipe la declara, y la herramienta validate de aggrega mcp responde valid: true con la advertencia entre sus notices.

Qué no comprueba la corrección de una sola entidad

Cuatro comprobaciones de una compilación real quedan fuera del alcance de una compilación de una sola entidad, y validate renuncia a cada una en lugar de informar de un hallazgo que no puede respaldar.

Un origen que hay que descargar

Validar una sola entidad no lee ningún lockfile, no lee ni escribe ninguna caché y no realiza ninguna solicitud de red. Una Recipe cuyo source: nombra algo obtenido mediante un transporte —un repositorio de charts OCI o HTTPS, un repositorio Git— no tiene, por tanto, código de infraestructura desde el que renderizar: el chart o el módulo no existe en ningún lugar al que la ejecución pueda llegar, y nada en el archivo que se comprueba es incorrecto. Validate lo dice, lo imprime como un resultado distinto de un renderizado y termina con 0:

Entity: catalog/recipe/helm/openbao/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Resolution: valid
Render: not attempted (this Recipe's source is fetched)
Validating one entity on its own reads no lockfile, reads and writes no
cache, and makes no network request, so the chart or module this Recipe
names is never retrieved and there is nothing to render from. To render
it, build a Release that deploys a component this Recipe implements.

Todo lo que está por encima de esa línea se comprobó y se informa como válido. Lo que significa el código de salida para una Recipe así es, por tanto, más limitado que para una que se renderizó —el esquema, la forma y la resolución se cumplen; el renderizado no está demostrado— y el informe indica cuál de los dos estás leyendo.

Un origen que el workspace ya contiene no se aparta. Un source: ./module relativo no necesita descarga, así que su renderizado se intenta como cualquier otro, y un fallo en él es un hallazgo real que se informa como Render: not completed in isolation con un código de salida distinto de cero. La línea anterior solo aparece para un origen que hay que obtener.

Para renderizar de verdad una Recipe con origen descargado, ejecuta aggrega build sobre una Release que despliegue un componente que la Recipe implementa: una compilación resuelve el origen a través del lockfile de la Release y la caché local, que es lo que proporciona los bytes que validate no tiene forma de obtener.

Un socket uses obligatorio

La segunda es si los sockets uses required: true del Component de implements están poblados.

Un socket obligatorio se puebla conectando una arista a otro componente: desde el propio bloque uses del Aggregate, o desde una Release que conecta un socket que declara el Component. El arnés sintetizado contiene una única instancia, por lo que no contiene ningún segundo componente al que pueda apuntar esa arista, y ninguna redacción de los documentos sintetizados puede producir uno: inventar un par significaría inventar recursos de cómputo que el arnés nunca declaró. Por tanto, validate nombra los sockets que no comprobó y continúa con la resolución y el renderizado:

Sockets: required uses sockets not checked (backend, cache, registry)
Validating a Recipe on its own places its Component in a build of one,
so no other component exists for a required socket to be wired to. Whether
each of these sockets is populated is checked when the Component is deployed
in an Aggregate.

La línea solo aparece cuando el Component declara al menos un socket obligatorio, y nombra solo los obligatorios: un socket opcional nunca se enumera, porque dejarlo sin conectar no es un hallazgo en ningún ámbito. Una Recipe cuyo Component no declara ningún socket obligatorio no produce esa línea, y su informe no cambia.

La regla en sí no se relaja ni se duplica; se plantea en el ámbito que puede responderla. aggrega build la aplica por completo sobre las superficies de aristas del Aggregate y de la Release en conjunto, y se detiene ante un socket obligatorio que nada conecta. Así, una Recipe que supera la validación de una sola entidad todavía tiene que cumplir la regla de sockets obligatorios cuando se despliega su Component, y el informe lo dice en lugar de dejar una diferencia silenciosa entre lo que comprobó validate y lo que comprobará una compilación.

Una ranura de adjunto obligatoria o un mandato de presencia

La tercera es si las ranuras de adjunto required: true del Component de implements —los puntos de vinculación con nombre que declara su featuresSchema— están ocupadas, y si está presente un adjunto de cada tipo de Feature que exigen sus mandatos de presencia.

Una ranura obligatoria se ocupa adjuntando una Feature con ese nombre, en el Aggregate o en la Release, en el componente o en un ámbito superior: donde se despliega el Component, no en la Recipe. El arnés sintetizado no adjunta ninguna Feature, así que nada de lo que construye puede ocupar esa ranura. Por tanto, validate nombra las ranuras que no comprobó y continúa con la resolución y el renderizado, exactamente igual que con los sockets obligatorios:

Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.

La línea solo aparece cuando el Component declara al menos una ranura obligatoria, y nombra solo las obligatorias; una Recipe cuyo Component no declara ninguna no produce esa línea. Solo se aparta el requisito: la restricción de etiqueta de una ranura y sus mecanismos de entrega permitidos se mantienen tal como se declararon. Una plantilla que no se puede analizar sigue haciendo fallar la ejecución, y también un fallo propio de la Recipe, como un Workload que el provider no puede sintetizar, a menos que la Recipe también lea un valor que solo proporciona una conexión o una Feature adjunta, como describe la sección siguiente.

Un mandato de presencia —una anotación features.aggrega.ai/requiredType.<label> en el Component, que exige que algún adjunto lleve el tipo de Feature que nombra— se aparta por la misma razón: el arnés no adjunta nada, así que nada de lo que construye puede llevar ese tipo. Validate nombra cada mandato que no comprobó por su etiqueta y el tipo que exige, y continúa con la resolución y el renderizado. example/compute/service de la biblioteca estándar declara uno, por lo que su Recipe informa, antes de sus dos artefactos renderizados:

$ aggrega validate aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml --catalog aggrega-catalog
Entity: aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: presence mandates not checked (monitoring: core/prometheus-exporter)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to carry a type the Component requires. Whether
an attachment of each of these types is present is checked when a Release
that deploys the Component is built.
Resolution: valid
Render: 2 artifact(s)

Un mandato cuya declaración no se puede evaluar —el prefijo de la anotación sin etiqueta detrás, o un valor que no es un tipo de Feature— no se aparta: es un fallo propio del Component, que ningún adjunto repara, y validate hace fallar la ejecución por él igual que una compilación.

Cada regla se plantea donde se puede responder. aggrega pull, aggrega build y aggrega validate --release evalúan ambas sobre los adjuntos reales de la Release, y cada uno se detiene ante una ranura obligatoria que nada ocupa y ante un tipo exigido que ningún adjunto lleva.

Un valor que solo proporciona una conexión o una Feature adjunta

La cuarta es si una Recipe se renderiza una vez que sus conexiones y sus Features adjuntas proporcionan lo que leen sus plantillas.

Las plantillas de una Recipe leen lo que entrega una conexión en .context.inject y .context.uses, y lo que entrega una Feature adjunta en .features. El arnés sintetizado no conecta ninguna conexión ni adjunta ninguna Feature, así que cada una de esas lecturas no encuentra nada: una lectura en .context.inject.env encuentra un canal de entrega vacío, y un range sobre .context.uses no encuentra ninguna conexión. Validate renderiza primero la Recipe, y un renderizado que se completa se informa como de costumbre. Cuando el renderizado se detiene y las plantillas de la Recipe —incluidos los archivos y las entradas de biblioteca que importan— leen algo bajo esos tres, validate informa del renderizado como no intentado, nombra los valores que la Recipe lee allí, imprime la frase en la que se detuvo el renderizado y termina con 0. La variante chart del ejemplo MariaDB + Adminer lee sus credenciales de base de datos del canal de entrega que llenan sus dos secretos adjuntos:

$ aggrega validate catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml --release release-helm-chart.yaml
Entity: catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.
Resolution: valid
Render: not attempted (this Recipe reads values a build of one cannot supply)
Validating a Recipe on its own places its Component in a build that wires
no connection and attaches no Feature, so nothing supplies what its
templates read under .context.inject, .context.uses or .features. Its
render stopped, and whether on one of those values or on a fault of its
own is not judged here. To render it, build a Release that deploys a
component this Recipe implements.
Reads: .context.inject.env.MARIADB_PASSWORD, .context.inject.env.MARIADB_ROOT_PASSWORD
The render stopped: rendering: [CATALOG_ERROR] instance instance: rendering node "instance": [CATALOG_ERROR] catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml: recipe "mariadb-chart" valuesMapping: [CATALOG_ERROR] valuesMapping[mariadb-chart]: template "valuesMapping[mariadb-chart]" execute: template: valuesMapping[mariadb-chart]:7:30: executing "valuesMapping[mariadb-chart]" at <.context.inject.env.MARIADB_ROOT_PASSWORD>: nil pointer evaluating interface {}.MARIADB_ROOT_PASSWORD

Una lectura que no encuentra nada y no detiene nada no se aparta: un range sobre .context.uses que no renderiza nada, en un renderizado que se completa, se informa como el renderizado que fue.

Lo que lo decide es lo que lee la Recipe, no aquello en lo que se detuvo el renderizado, y eso tiene una consecuencia que conviene conocer antes de encontrarla: un fallo propio de la Recipe en una Recipe que también lee un valor así —una clave mal escrita, por ejemplo— se informa como no intentado junto con el resto, no como un fallo. La línea The render stopped: lleva la propia frase del renderizado para que puedas ver de cuál se trataba, y una compilación de una Release que despliega el Component juzga el renderizado por completo.

Dos fallos siguen haciendo fallar la ejecución lea lo que lea la Recipe, porque ninguna conexión ni Feature los cambia: una plantilla que no se puede analizar, y una referencia que el renderizado rechaza —una raíz que el contexto de renderizado no define, o una clave mal escrita bajo una raíz cuya forma es fija, como .context.instance_idd—. Una aserción que declara la Recipe y que llama a fail no se aparta ni es un fallo, lea lo que lea la Recipe: se informa como la advertencia que una aserción fallida siempre es. Una Recipe cuyas plantillas no leen ninguno de los tres tiene su renderizado juzgado por completo, y un renderizado que se detiene falla con la frase que nombra la causa.

La herramienta validate de aggrega mcp da el mismo veredicto sobre la misma Recipe: un renderizado apartado de este modo responde como válido sin nada en sus diagnósticos, y las líneas anteriores están en el texto que devuelve junto a ellos.

La carga del catálogo en el modo de una sola entidad es tolerante: una entidad defectuosa no relacionada en otra parte del catálogo se omite en lugar de abortar la comprobación, por lo que nunca bloquea la validación aislada del destino.

Un archivo omitido sigue explicando un Component que falta por su causa. Cuando no se encuentra el destino implements de una Recipe y exactamente un archivo omitido declara ese Component, el informe empieza con el rechazo propio de ese archivo — su ruta, la restricción que incumple y el código corto de la condición en el encabezado —, seguido de una note: que dice que el archivo se omitió durante la carga, de modo que el catálogo no contiene nada bajo la identidad que declara, y después del fallo implements target … not found in catalog como el motivo por el que se necesitaba el archivo. Cuando ningún archivo omitido declara ese Component, o lo declara más de uno, el fallo de no encontrado va primero y cada archivo omitido se lista debajo bajo note: catalog files skipped at load. Esta es la explicación que aggrega build da de un archivo que omitió, y también la dan la comprobación de entidades del editor mediante aggrega serve y la herramienta validate de aggrega mcp. Un catálogo del que no se omitió nada informa exactamente como lo haría en otro caso.

Cómo se relaciona validate con lint y build

Los tres comandos cubren tres preguntas distintas:

  • aggrega validate: ¿es correcto? Esquema, pilares, referencias, extends, capacidad según el tipo de entrada y renderizado aislado. No lee ningún estado de tiempo de ejecución ni emite artefactos.
  • aggrega lint: ¿sigue esto las convenciones de publicación del catálogo? Nomenclatura, alineación entre categoría y directorio, prefijos de anotación, tamaño del incremento de versión y el resto de la disciplina de publicación opcional. Lint refleja los tres ámbitos de validate, pero nunca comprueba la corrección.
  • aggrega build: compilar un despliegue completo. Build necesita un cierre completo de Aggregate + Manifest + Release y emite artefactos nativos del provider. Valida su propio cierre de dependencias como parte de la compilación y después renderiza. aggrega validate --release es esa validación de dependencias por sí sola, sin el renderizado; validate de una sola entidad aísla el renderizado de una única Recipe sin un Aggregate completo.

Ejemplos

Validar todo el catálogo:

aggrega validate --catalog ./catalog

Validar exactamente aquello de lo que depende una Release, antes de compilarla:

aggrega validate --release releases/production.yaml

Validar una entidad y, para una Recipe, ver su salida renderizada de forma aislada:

aggrega validate core/datastore/postgres/recipes/helm.yaml

Validar una entidad en los términos de una Release a la que la configuración del workspace asigna directorios de catálogo propios:

aggrega validate core/datastore/postgres/recipes/helm.yaml --release releases/production.yaml

Véase también

  • ./aggrega-lint.md: la contraparte de convenciones en los mismos tres ámbitos.
  • ./aggrega-build.md: compila un Aggregate + Release completo en artefactos; valida su cierre de dependencias como parte de la compilación.
  • ./aggrega-inspect.md: consultar el grafo IR tras la resolución sin pasar al renderizado.
  • ../errors/warnings.md: los hallazgos informativos que validate muestra como líneas notice:.

Sinopsis

aggrega validate [entity-path] [flags]

Descripción

Check CORRECTNESS across three symmetric scopes.
With no argument, validate checks the WHOLE catalog: schema-pillar
structure, cross-document library resolution, extends chains, and provider
input-kind capabilities, over every catalog entity. Where the workspace
configuration gives its Releases catalog directories of their own under
workspace.releases, it checks the catalog once for each Release, over the
directories that Release reads, and reports each pass under a line naming
its Releases and those directories; Releases reading the same directories
share one pass.
With --release, validate checks the entities a Release's dependency closure
reaches: closure-scoped pillars, extends, and pre-render authored-value
conformance — the same correctness a build applies, scoped to that Release.
It then evaluates the Recipe and FeatureRecipe assertions against the values
that Release resolves to, as a build does before it renders, and reports a
failing assertion as a build reports it. Nothing is rendered.
With an entity path, validate checks one entity file. The kinds it accepts
as a single-entity target are Component, Feature, Recipe, FeatureRecipe,
Workload and Plugin. A value the kind requires that the file leaves empty is
reported first, as a placeholder still owed: every one is named at once, with
what it takes, read from the kind's own schema. That reading is this scope's
alone; a whole-catalog run, a Release's closure and a build do not apply it.
Each kind then has its schema checked, then the checks its own kind carries:
pillar structure for a Component or Feature; shape for a Workload,
FeatureRecipe or Plugin; and for a Recipe, shape plus an end-to-end compile
against a minimal generated harness, so its resolution, its guards and a
render of its output are all exercised. Where that Recipe's source is one
that has to be fetched, the render is reported as not attempted instead:
validating one entity on its own reads no lockfile, reads and writes no cache
and makes no network request, so the chart or module it names is never
retrieved and there is nothing to render from. A render that stops while the
Recipe's templates read what only a connection or an attached Feature
supplies — anything under .context.inject, .context.uses or .features — is
reported as not attempted too: the generated harness wires no connection and
attaches no Feature, so that render cannot be judged there, and a fault of
the Recipe's own beside such a read is set aside with it. A template that
does not parse and a reference the render refuses still fail. An assertion
that calls fail, the Recipe's own or one its Component declares, is printed
as a warning closed by a sentence saying a Release must satisfy it before a
build can pass, and does not fail the check: the generated harness sets none
of a real Release's values, so it cannot tell an assertion waiting on one from
one that is broken, and a build still halts on it. Any other kind is refused here
today, and the refusal names the scope that checks it instead: a whole-catalog
run reaches an Aggregate and the library kinds when they sit in a catalog
directory, and --release reaches a Release, the Manifest it names and the
Aggregate it deploys.
With an entity path and --release together, the entity is checked in that
Release's terms: its references — the Component a Recipe implements, a
library a pillar refers to — resolve through the catalog directories the
workspace configuration gives that Release rather than the workspace's own,
so a workspace keeping one catalog variant per Release checks an entity
against the variant that Release builds with. The checks are the entity
path's; no closure is validated.
The command writes nothing to disk.

Flags

FlagPredeterminadoDescripción
--catalog[]Directorio de catálogo; repetible. Cada —catalog <dir> se antepone a la pila de búsqueda del catálogo (gana la primera coincidencia): los catalog_dirs del workspace o, para una Release a la que la configuración del workspace asigna directorios propios en workspace.releases, los de esa Release; la pila termina con el directorio llamado catalog en la raíz del workspace cuando existe. Una lista catalog_dirs escrita vacía no lee ningún catálogo local.
--ir-graphfalseEscribe además en stdout, como JSON, el grafo IR que calculó esta ejecución, además de todo lo que este comando ya produce. Los valores que un autor declaró sensibles se retienen de él; pasa —unredacted para imprimirlos en su lugar. Se aplica al ámbito —release, el único ámbito que resuelve una Release en un grafo. Selecciona un DOCUMENTO, mientras que —response-format establece cuánto del propio informe de este comando se escribe; ninguno afecta al veredicto ni al código de salida
--no-unsupported-field-warningsfalseSilencia la clase de advertencias de campos no admitidos: los avisos que emite un destino por algo que escribiste y que no puede respetar —un campo de Workload que no puede expresar (como ocurre con un destino de menor fidelidad como compose), o una anotación aggrega.ai/ sobre la que no actúa para el tipo de entrada del nodo—. Las demás advertencias de renderizado siguen apareciendo. Solo de visualización; no cambia la salida renderizada. Se aplica al ámbito de entidad, el único ámbito que renderiza
--plugin—Ruta a un .wasm sin procesar que se valida contra su autoinforme describe(): la comprobación de autoría previa a la publicación. Sola necesita —type; con un argumento de entidad Plugin, contrasta el binario con el tipo declarado de la entidad, la declaración de capacidad, el reflejo de comandos y el registro de funciones del host.
--release—Ruta a un YAML de Release. Sola, valida sobre su cierre de dependencias resuelto; con un argumento de entidad, comprueba esa entidad en los términos de la Release, con sus referencias resueltas a través de los directorios de catálogo que la configuración del workspace asigna a esa Release. Una ruta relativa se resuelve contra el directorio en el que ejecutas el comando, no contra la raíz del workspace. Cuando ese directorio no está en ningún workspace y no se nombra ninguna raíz, una ruta absoluta encuentra el workspace a partir de la propia carpeta de la Release
--response-formatdetailedVolumen de salida para el ámbito —release, el cierre de una Release sin argumento de entidad: detailed (por defecto) informa de cada diagnóstico más las líneas informativas; concise informa del número de diagnósticos y solo del primero. El veredicto y el código de salida son idénticos en ambos.
--type—Tipo de plugin para una comprobación —plugin solo del binario, verificado contra el tipo que el propio binario declara. Solo tiene sentido con —plugin; cuando una entidad Plugin proporciona el tipo, omítelo (un valor discordante provoca una detención).
--unredactedfalseImprime los valores que un autor declaró sensibles en lugar de retenerlos. Cualquier cosa a la que llegue la salida —un terminal, una tubería, un archivo, una grabación de pantalla— contiene entonces esos valores en claro. Alcanza el grafo que escribe —ir-graph y nada más, por lo que requiere —ir-graph