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

aggrega lint

aggrega lint comprueba las convenciones de publicación — nomenclatura, alineación entre categoría y directorio, prefijos de anotación, disciplina en la escritura de esquemas y tamaño del incremento de versión. Tiene tres modos, seleccionados por su argumento, que aplican la misma disciplina de convenciones en tres ámbitos: el catálogo completo (sin argumento), el cierre de dependencias de una sola Release (--release) y el archivo de una entidad (una ruta de entidad, con una puerta de publicación --pre-publish opcional). Cada ámbito responde a la misma pregunta — «¿sigue este contenido la disciplina de publicación del catálogo?» — sobre una porción distinta del catálogo.

Las convenciones son distintas de la corrección. aggrega lint nunca comprueba si el contenido está bien formado o si compilaría — eso es aggrega validate, que refleja los mismos tres ámbitos para el esquema, los pilares, la resolución de referencias, extends, la capacidad del tipo de entrada y el renderizado. Un selector de socket o de slot que la gramática de selectores no puede leer es un fallo de corrección, así que lint no informa nada sobre él: validate lo rechaza, sobre todo el catálogo o sobre un solo Component o una sola Feature — consulta selectores declarados. Los dos comandos son complementarios: validate te dice si el contenido es correcto; lint te dice si es publicable según las convenciones del catálogo.

aggrega lint es opcional. El propio compilador se mantiene sin opiniones propias sobre la disciplina del catálogo; estas reglas residen en un plugin independiente que eliges ejecutar. Un workspace que nunca ejecuta aggrega lint sigue construyéndose y publicándose.

La ruta de la entidad puede darse de forma posicional o con --entity <path>. --release es mutuamente excluyente con un argumento de entidad — seleccionan ámbitos distintos; pasar ambos provoca una detención.

Convenciones en todo el catálogo (sin argumento)

aggrega lint sin argumento ejecuta las reglas estructurales de disciplina de publicación sobre cada entidad del catálogo encontrada en los directorios de catálogo configurados. Los hallazgos son orientativos — se informan con severidad warn y nunca detienen la ejecución solo por un hallazgo de convención. Úsalo para revisar un catálogo en busca de desviaciones de nomenclatura, de categoría y directorio y de prefijos de anotación. Un Aggregate, un Manifest, una Release o un Workload en un directorio de catálogo se omite en lugar de comprobarse: la pasada cuenta cada uno de esos tipos en una línea not checked: tras su resumen y te remite al modo de entidad, que comprueba un documento de cualquier tipo.

Un archivo YAML bajo un directorio de catálogo es un documento de Aggrega cuando una de sus líneas empieza, sin sangría, con apiVersion: y un valor que comienza por aggrega.ai/, entre comillas o no. Un documento de Aggrega que no se puede leer, cuyo YAML no se puede analizar, o cuyo kind, metadata o spec no tiene la forma que adopta el envoltorio 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 analiza nada con lint y no se imprime ninguna línea conventions checked. 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, nombrado 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 values de un chart, las definiciones de workflow — se omite. --release se detiene de la misma manera ante un documento así bajo sus directorios de catálogo.

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 comprueba una sola vez, sobre su pila de búsqueda: los directorios --catalog, después workspace.catalog_dirs y después el directorio catalog en la raíz del workspace, si 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 una sola pasada sobre todas leería todas las variantes a la vez — con la entidad de una variante ocultando la de otra. Así que se comprueba una vez por cada Release que contiene el workspace, sobre los directorios que lee esa Release, con los directorios --catalog en primer lugar 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 de los hallazgos de esa pasada y de su propio resumen:

    Release release-compose.yaml reads catalog-compose
    conventions checked: 7 entities, 0 advisory finding(s)
    Release release-helm-synth.yaml reads catalog-helm-synth
    conventions checked: 8 entities, 0 advisory finding(s)

    Las Releases que leen exactamente los mismos directorios comparten una pasada, que nombra a cada una de ellas, de modo que un hallazgo allí se informa una sola vez. 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. Con -o json, el documento también lleva passes: los releases, catalogDirs, findings y summary de cada pasada, mientras que los findings y summary de nivel superior cubren todas las pasadas juntas. Las Releases que contiene un workspace son sus documentos de 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: coloca las entidades en catalog/, pasa --catalog o establece workspace.catalog_dirs — o, en un workspace que nombra Releases, el catalog_dirs propio de una Release en workspace.releases. Nunca enumera implícitamente el directorio de trabajo actual.

Un enlace bajo un directorio de catálogo que lleva fuera del workspace — o fuera de un directorio que nombraste fuera de él — no se lee, y la ejecución se detiene ahí, nombrando el enlace, en lugar de informar como limpio un catálogo uno de cuyos documentos no pudo leer; una build sobre los mismos directorios se detiene en el mismo enlace. El límite del workspace expone la regla y sus soluciones.

Convenciones en una Release (--release)

aggrega lint --release <release-path> ejecuta las mismas reglas estructurales sobre los archivos de entidad del catálogo que alcanza el cierre resuelto de una sola Release, en lugar de sobre todo el catálogo o una sola entidad. Calcula el cierre con la misma maquinaria que usa una build y luego analiza el archivo de catálogo propiedad del autor de cada entidad. Una entidad fijada desde un registry que reside en una ranura de la caché no tiene ningún archivo local que analizar y se omite — las reglas de publicación se aplican a los archivos escritos localmente. Como en el modo de catálogo completo, los hallazgos son orientativos y nunca detienen la ejecución solo por un hallazgo de convención.

Este es también el único ámbito que tiene en sus manos una Release completa, así que es donde se ejecutan las reglas que leen una — la regla de credenciales de conexión descrita en Las reglas de disciplina. Una regla así se ejecuta una vez por comprobación, después de las reglas por entidad, sobre tres documentos: el Aggregate que despliega la Release, tal como lo escribió su autor; la Release, con su cadena extends incorporada, de modo que una Release hija lleva lo que hereda; y, para cada componente que declara el Aggregate, el Component del que ese componente es una instancia, tal como lo resuelve el catálogo. Ningún valor de parámetro está entre ellos, como en todos los ámbitos: la Release llega sin su bloque parameters, incluidos los valores que hereda de una base, y el Aggregate sin sus valores predeterminados ni los valores que pasa a cada módulo que importa — consulta Qué recibe un plugin de linter. Sus hallazgos se informan bajo el archivo de la Release.

Esta es la contraparte, en cuanto a convenciones, de aggrega validate --release, que comprueba la corrección del mismo cierre.

Los linters que ejecuta este ámbito quedan sujetos al registro de identidades de plugins de confianza junto a la Release, igual que los sujeta una build. Antes de que se ejecute cualquiera de ellos, --release compara las vinculaciones plugins.linter configuradas con el registro de confianza de plugins: un plugin registrado que la configuración ya no vincula — un linter o una puerta — detiene la pasada, y un linter leído de la caché cuyo artefacto no es el registrado se rechaza en lugar de ejecutarse. Un linter leído de la caché también queda sujeto a su firma registrada cuando se carga: donde su entrada registra una firma verificada, el material de firma que ese hecho nombra en la caché se comprueba de nuevo, y la pasada se detiene con E0144 si falta o difiere, y con E0332 si se creó para un plugin distinto del linter leído — 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, una entrada que no registra ninguna — o la ausencia de entrada para el linter, incluido un registro eliminado — detiene la pasada con E0331, con la misma configuración con la que aggrega pull lo rechazaría por no estar firmado. Cada uno de los tres nombra su solución, aggrega pull --release <release>, que verifica la firma del linter en su registry, la registra y almacena en caché el bundle que nombra, reescribiendo una copia en caché que ya no coincide con su digest. Un linter servido desde la copia incluida en el binario del compilador nunca queda sujeto al requisito. Estos son fallos de la pasada, no hallazgos de convención, por lo que detienen la ejecución donde un hallazgo no lo haría. Los ámbitos de catálogo completo y de entidad única no nombran ninguna Release ni leen ningún registro, así que un linter que leen de la caché se comprueba solo contra su manifiesto en caché. Antes de todo eso, --release nombra cada retirada registrada sobre aquello de lo que depende la Release, como una línea deprecation: con las palabras que imprime aggrega build — tanto un marcador que el lockfile registra contra una referencia fijada como uno que el registro de confianza registra contra un linter o una puerta —, de modo que la pasada lo indica incluso donde uno de los rechazos anteriores la detiene. Una retirada no cambia ningún hallazgo ni ningún código de salida, y un registro de confianza que está y no puede leerse detiene la pasada en lugar de pasar por uno que no registra nada.

Disciplina de entidades: local y puerta de publicación

El modo de ruta de entidad se ejecuta con una de dos severidades:

  • Predeterminado (local). Ejecuta las reglas de disciplina sobre el contenido local de la entidad con severidad warn. Sin acceso al registry; se omite la comprobación del incremento de versión. Úsalo mientras escribes.
  • --pre-publish (puerta de publicación). Obtiene del registry la última versión publicada que no sea preliminar de la entidad, ejecuta las mismas reglas con severidad halt y, además, clasifica el cambio como PATCH / MINOR / MAJOR y se detiene si el incremento propuesto de metadata.version es menor de lo que requiere el cambio. Úsalo en el flujo de publicación, antes de aggrega push. --pre-publish se aplica solo a la forma de entidad única.

Un incremento excesivo siempre está permitido; un incremento insuficiente provoca una detención. La primera publicación de una entidad (sin versión previa en el registry) omite la comprobación del incremento y muestra una advertencia que indica que no se realizó ninguna verificación.

Qué tipos comprueba el modo de entidad

El modo de entidad aplica el lint al documento que nombras, sea cual sea su tipo, y lo entrega a cada regla que lee una sola entidad. Cada regla decide por sí misma qué tipos describe, y una regla a la que se entrega un tipo que no describe no informa nada. Así, nombrar un Aggregate, un Manifest, una Release o un Workload — tipos que la pasada sobre todo el catálogo omite y enumera en su línea not checked: — ejecuta también las reglas sobre él, y solo las reglas que describen ese tipo pueden informar:

ReglaTipos sobre los que informa en el modo de entidad
Prefijo de anotaciónCualquier tipo: lee metadata.annotations sea cual sea el tipo del documento.
Extensiones x-aggrega-* directasCualquier tipo: lee spec.schema sea cual sea el tipo del documento.
Forma del nombreComponent, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary y ArtifactLibrary.
Categoría que coincide con el directorioComponent.
Slot secreto que declara sensitiveComponent y Feature.
Anotación de credenciales de métricas que coincide con providesComponent.
Provides declarados por el ComponentRecipe.
Refs dinámicas, sobrescrituras de IdSchemaLibrary.
Límites predeterminados del PluginPlugin.
La comparación del incremento de versión (--pre-publish)Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate y Plugin (un plugin integrado en el compilador no se compara); un cambio en cualquier otro tipo se clasifica como MAJOR.
Credencial de conexión que coincide con la clave de destinoNinguno: lee una Release completa, así que solo se ejecuta con --release.

Un Aggregate, un Manifest, una Release y un Workload no declaran ni metadata.annotations ni spec.schema en sus esquemas, así que un documento de uno de ellos que se ajusta al esquema de su tipo no recibe nada de las dos reglas que leen cualquier tipo; esas dos informan sobre él solo cuando lleva de todos modos una de esas claves, que el esquema de su tipo rechaza como propiedad inesperada. Lo que añade nombrar un Aggregate es la comparación del incremento de versión con --pre-publish, que lo compara con su versión publicada como describe la rúbrica de abajo.

La rúbrica del incremento de versión

En el modo --pre-publish, el cambio se compara con la versión publicada anterior y se clasifica:

  • PATCH — cambios solo en la documentación o en los comentarios.
  • MINOR — cambios estrictamente aditivos (un nuevo campo opcional, una nueva entrada).
  • MAJOR — eliminaciones, restricción de tipos o un campo antes opcional que pasa a ser obligatorio.

La comparación depende del tipo de entidad: Component, Feature y SchemaLibrary se comparan teniendo en cuenta sus campos que contienen esquemas; MappingLibrary se compara a nivel de clave de entrada (los cuerpos de las entradas son opacos, así que un cuerpo modificado se trata de forma conservadora como MAJOR); Recipe y FeatureRecipe se comparan en sus campos fundamentales. Un Aggregate se compara en sus declaraciones de parámetros, sus componentes y sus subsistemas; el valor predeterminado de un parámetro no llega a la comparación más de lo que llega cualquier otro valor de parámetro (consulta Qué recibe un plugin de linter), así que un cambio limitado a un valor predeterminado — añadirlo, cambiarlo o eliminarlo — no forma parte de ella, ni tampoco un cambio en una clave fuera del vocabulario de slots de parámetros. Un incremento insuficiente provoca una detención con un diagnóstico que nombra el incremento requerido.

Las reglas de disciplina

La mayoría de las reglas tienen un ajuste por workspace bajo lint.publishing_discipline en .aggrega-config.yaml y una anulación de CLI correspondiente, y cada anulación tiene una contraparte --no-. La precedencia es --no-<flag> sobre --<flag> sobre el valor de la configuración del workspace, en todos los ámbitos: el catálogo completo, una Release y una entidad. Todas las reglas están activadas de forma predeterminada, y cada valor predeterminado se basa en la maquinaria de la plataforma o en una convención de catálogo documentada; los ajustes son exclusiones voluntarias para un workspace que tenga un motivo para relajar alguna.

Las reglas que no tienen ningún ajuste lo indican en su entrada más abajo, y el motivo es el mismo en cada caso: informan de un hecho sobre la entidad y dejan la decisión al autor, así que no hay ningún juicio que relajar. La rúbrica del incremento de versión descrita arriba tampoco tiene ninguno — compara el contenido propuesto con la versión publicada e informa de lo que requiere el cambio, que es una propiedad del cambio y no una preferencia del workspace.

  • Prefijo de anotación — los espacios de nombres reservados (aggrega.ai/, y feature.aggrega.ai/ fuera de una Feature) pertenecen a la plataforma y se rechazan en otras claves. Activada de forma predeterminada; desactivable con allow_aggrega_ai_prefix.
  • Forma del nombre — cada tipo de entidad tiene una convención de forma de nombre (número de segmentos para los tipos cloud-native; PascalCase para los tipos de biblioteca). Activada de forma predeterminada; desactivable con allow_nonstandard_names.
  • Referencias dinámicas — las entradas de una SchemaLibrary no pueden usar $dynamicAnchor / $dynamicRef (la expansión de $ref en tiempo de compilación de la plataforma no puede resolverlas). Activada de forma predeterminada; desactivable con allow_dynamic_refs.
  • Anulaciones de id — las entradas de una SchemaLibrary no pueden declarar su propio $id (la plataforma deriva el $id canónico). Activada de forma predeterminada; desactivable con allow_id_overrides.
  • La categoría coincide con el directorio — la etiqueta component.aggrega.ai/category de un Component debe coincidir con el primer segmento de directorio bajo core/, tomado del conjunto cerrado de categorías (ai-agent, ai-model, ai-tool, ai-pipeline, datastore, gateway, mesh, network, messaging, storage, compute, observability, security, bigdata, devtool). Activada de forma predeterminada para las entidades bajo una ruta core/; desactivable con allow_category_mismatches.
  • Extensiones x-aggrega-* directas — escribir directamente claves x-aggrega-* en un esquema de Component o de Feature se desaconseja en favor de la vía de escritura de primera clase. Activada de forma predeterminada; desactivable con allow_direct_x_aggrega_extensions.
  • Provides declarados por el Component — el spec.provides de una Recipe publica una clave por entrada, y el Component que implementa la Recipe declara, en el pilar provides de su spec.schema, qué claves expone el tipo. Es con esa declaración con la que se comprueba una referencia inject from:, de modo que una clave que una Recipe publica sin que el Component la declare se produce y luego se rechaza donde un consumidor la conecta. Publicar más allá del contrato declarado se acepta en tiempo de build, por eso el hallazgo es orientativo y no un rechazo. Activada de forma predeterminada para las Recipes; desactivable con allow_undeclared_recipe_provides.
  • Límites predeterminados del Plugin — el spec.runtime de un Plugin lleva maxMemoryPages y timeoutMs, los dos límites que aplica el host cuando carga y ejecuta el plugin. Un Plugin que no fija ninguno de los dos se ejecuta con los valores predeterminados de la plataforma, lo cual es un resultado seguro y no un error, así que la regla informa de que los valores predeterminados están en vigor y de que hay límites explícitos disponibles para fijar. Activada de forma predeterminada para las entidades Plugin; no tiene ningún ajuste.
  • El slot de secreto declara la sensibilidad — un slot de vinculación puede fijar, mediante su selector de etiquetas, el tipo de Feature que lo ocupa a secret, y puede declarar por separado sensitive: true para registrar que lo que lo ocupe maneja material secreto. El selector indica qué ocupantes son admisibles; el marcador indica el tratamiento. Un slot que fija el tipo y no declara ningún marcador deja que ese tratamiento se vuelva a deducir del selector en lugar de leerse directamente. La regla lee cada slot que declara una entidad: los de su propio bloque de vinculaciones bajo spec.featuresSchema y, en un Component, los que cada socket de dependencia declara bajo spec.usesSchema.<socket>.featuresSchema para las conexiones que pasan por él — un hallazgo sobre el slot de un socket nombra el socket además del slot. Activada de forma predeterminada para Components y Features; no tiene ningún ajuste.
  • La credencial de la conexión coincide con la clave del destino (connection-credential-matches-target-key) — un servidor que comprueba una clave guarda la clave que verifica en un slot de su propio Component, y un llamador presenta una clave en la conexión a través de la cual llega al servidor. Ninguno de los dos extremos ve los adjuntos del otro, así que ambos tienen una misma clave solo porque sus autores la escriben en los dos extremos — normalmente haciendo que ambos adjuntos lean un mismo parámetro — y una build nunca los compara. Esta regla sí lo hace, y es la única regla que lee una Release completa, por lo que se ejecuta con --release y en ningún otro ámbito. Encuentra ambos extremos por los nombres que les da el catálogo estándar: la clave del destino es el slot api_key que su Component declara en spec.featuresSchema, y la del llamador es el slot credential en la conexión, escrito en uses.<socket>.<alias>.features.credential en el Aggregate o en una conexión que la Release conecta. Para cada conexión cuyo destino declara api_key y no está etiquetado como managed, informa de una conexión que lleva una credencial a un destino cuyo slot de clave no está rellenado, de un slot de clave rellenado sin credencial en la conexión, y de dos extremos que nombran su secreto de forma distinta. Lo que compara es el localizador de cada extremo — el origin que escribe un adjunto, en values en el Aggregate o en infra en la Release — tal como lo escribió el autor, de modo que dos extremos que leen un mismo parámetro se consideran iguales y dos literales se comparan por su texto; no se resuelve nada, y un hallazgo nombra el componente, la conexión, el destino y los dos slots pero nunca cita ninguno de los dos localizadores, ya que el texto escrito allí puede ser el propio secreto. Un destino que no declara ningún slot api_key no produce nada, y un slot que no es la clave del llamador, como el token de pull del registry de un servidor de modelos, nunca se lee. Tampoco se juzga un destino cuyo Component está etiquetado como component.aggrega.ai/hosting: managed, contenga lo que contenga su slot api_key: un Component así representa un servicio que opera su proveedor, de modo que nada de lo que ejecuta la Release comprueba una clave en él, y donde declara api_key — la clave de una API de modelos alojada, por ejemplo, con el nombre que le da el producto del proveedor — el slot contiene la clave que la Release presenta a ese proveedor, nunca una que presenten sus llamadores. Un destino etiquetado como self-hosted, external o mixed, o sin etiqueta de alojamiento, sí se juzga. Una conexión en el socket scrape_target — el nombre que el catálogo estándar da al socket a través del cual un scraper de métricas llega a sus destinos — es un scrape, y si la credencial de un scrape debe ser la clave de llamador del destino depende del producto del destino: algunos sirven sus métricas sin credencial, otros las ponen detrás de la clave que presenta cada llamador, y otros aceptan un token propio. Así que, para un scrape, la regla lee lo que el Component del destino indica en su anotación observability.aggrega.ai/metrics-credential: con none el scrape no se juzga en absoluto; con separate-token su credencial nunca se compara con la api_key del destino, por lo que no se informa de ninguno de los tres hallazgos sobre él; con target-key se juzga como cualquier otra conexión. La regla lee solo esos tres valores, de modo que un scrape a un destino sin la anotación, o con cualquier otro valor, se juzga como cualquier otra conexión — y toda conexión en otro socket, incluida una conexión a un modelo, a una herramienta o a un datastore, se juzga igual diga lo que diga la anotación del destino. Lee los adjuntos escritos en el destino y en la conexión: un adjunto api_key que llega al destino desde un subsistema o un límite deja en cambio esa conexión sin juzgar, uno que añade una anotación no está entre ellos, así que un slot de clave rellenado solo de esa forma se lee como no rellenado, un extremo cuyo adjunto no escribe ningún localizador se compara solo en cuanto a si está rellenado, y un componente que aporta un módulo importado no se lee. Como los nombres de los slots, la etiqueta de alojamiento, el nombre del socket de scrape y la anotación de métricas son convenciones del catálogo que ninguna palabra clave del esquema marca, un catálogo que nombra los slots de otra forma no produce nada, un socket de scraping con otro nombre se juzga como cualquier otro socket, y un Component que guarda la clave de un proveedor en un slot llamado api_key sin la etiqueta managed se lee como un destino que comprueba esa clave, ya que el nombre del slot, la etiqueta y la anotación son todo lo que la regla lee del Component de un destino. Activada por defecto; se desactiva con allow_connection_credential_mismatches.
  • La anotación de credencial de métricas coincide con provides (metrics-credential-annotation-matches-provides) — un Component puede indicar dos hechos sobre sus métricas. Su anotación observability.aggrega.ai/metrics-credential indica cómo se autentican las métricas del producto: none, se sirven sin credencial; target-key, aceptan la clave que el Component exige a todo llamador, la que contiene su slot api_key; separate-token, aceptan un token propio. La clave provides metrics_credential_required, declarada en el pilar provides de su spec.schema, es lo que cada una de sus Recipes publica para indicar si las métricas de una instancia necesitan una credencial — lo cual puede depender de cómo esté configurada la instancia, ya que las métricas detrás de la clave del llamador solo necesitan una mientras haya una clave adjunta, de modo que la anotación no puede sustituirla. Ambas expresan un único hecho sobre el producto, así que esta regla exige que coincidan: un Component anotado como none que declara la clave, y uno anotado como target-key o separate-token que no la declara, se notifican cada uno, y el hallazgo nombra el Component, el valor de la anotación y la clave que sobra o falta. Un Component sin la anotación, o con cualquier otro valor, no produce nada. La regla lee el Component tal como está escrito, de modo que un Component que extiende a otro — cuyo esquema es el de su base — no produce nada y su base se lee donde está declarada, y un pilar provides escrito como referencia, como composición o como cuerpo escapado escrito como texto no es uno que pueda enumerar, por lo que ese Component tampoco produce nada. Activada por defecto para los Components; no tiene ningún ajuste.

La inmutabilidad de los artefactos no es una de estas reglas, y no tiene ningún ajuste. Un name:version publicado es definitivo: aggrega push compara el digest ya publicado en esa etiqueta con el digest que produciría el contenido a punto de subirse, y se niega a sobrescribirlo con contenido distinto. Volver a subir contenido idéntico byte a byte no sube nada y solo adjunta lo que a esa publicación aún le falta — su fecha de publicación, y su firma donde el push firma. Ningún flag ni ningún ajuste de la configuración del workspace relaja esto, porque el registry no expone ninguna vía de sobrescritura que un operador pueda elegir habilitar. El contenido modificado se publica con una nueva versión; --pre-publish es lo que verifica ese incremento frente a la release anterior.

Los flags de anulación por regla son controles por invocación y, intencionadamente, no tienen variable de entorno — ya están respaldados por la configuración en .aggrega-config.yaml bajo lint.publishing_discipline. El modelo general de precedencia AGGREGA_* se describe en environment-variables.md.

Tiempo de build y tiempo de publicación

La regla que desaconseja x-aggrega-* también se ejecuta durante aggrega build, donde aparece como advertencia; aggrega lint --pre-publish eleva el mismo hallazgo a error. Las builds locales llevan el aviso; la puerta de publicación lo impone.

Mientras escribes, en tu editor

Tu editor hace dos preguntas distintas sobre una entidad del catálogo, y son las dos con las que empieza esta página. ¿Es la entidad correcta — se analiza, se resuelven los pilares, se renderiza? Eso es aggrega validate, y una sesión del editor siempre lo responde. ¿Es la entidad publicable — sigue el nombre la convención, está el archivo en el directorio que espera su categoría, son correctos los prefijos de las anotaciones? Eso son estas reglas, y una sesión del editor solo lo responde cuando lo pides.

Está desactivado a menos que lo actives. Actívalo con serve.lint_on_validate en el .aggrega-config.yaml del workspace sobre cuyas entidades quieres recibir los consejos:

serve:
lint_on_validate: true

No hay ningún flag de línea de comandos para ello, y es deliberado: la pregunta trata sobre el contenido propio de un workspace concreto, y tú eres quien escribe ese workspace, no quien lanza el language server — eso lo hace tu editor.

Con él activado, cada entidad que validas lleva también estos hallazgos, cada uno con el nombre de la regla que lo produjo, junto a los de corrección. De ello se derivan tres cosas, y son las que lo hacen utilizable mientras escribes:

  • Los hallazgos siguen siendo orientativos. Una entidad que incumple una convención se valida igualmente, y su Release sigue resolviéndose y renderizándose. Activar el ajuste añade una capa de consejos; nunca hace que tu editor se niegue a funcionar.
  • Puedes distinguir ambos. Cada problema publicado nombra la capa que lo generó, de modo que un problema de nomenclatura y un fallo de resolución en el mismo archivo se leen como dos cosas distintas en lugar de como un único problema notificado dos veces.
  • Lo que has escrito es lo que se comprueba. Las reglas leen el búfer en lugar del archivo en disco, así que un nombre que corriges deja de notificarse antes de que guardes.

En esa capa solo se ejecuta el modo de contenido local: no se consulta ningún registry, no se descarga nada, no se escribe nada. A la comparación --pre-publish se llega pidiéndola — tu editor envía una solicitud para ello, igual que escribes --pre-publish en la terminal — y nunca editando el ajuste anterior. Una comprobación que se ejecuta cada vez que tocas un documento es precisamente donde no debe alcanzarse un registry, por lo que ese modo sigue siendo algo que invocas en lugar de algo que se ejecuta por su cuenta.

Pedir la comprobación explícitamente funciona diga lo que diga el ajuste, en los tres ámbitos anteriores. Así, un workspace que nunca ha activado la capa por edición puede pedir igualmente a su editor que recorra el catálogo, el cierre de una Release o una sola entidad — y obtener los mismos hallazgos que imprime este comando. El ajuste decide solo si la comprobación se ejecuta también donde no la pediste por su nombre.

Los detalles del protocolo se reparten entre dos páginas: qué significa la solicitud y cuándo enviarla está en la página aggrega serve de la referencia, y sus parámetros y la forma de su respuesta, campo por campo, están en la referencia del formato wire.

Elegir el linter

Las reglas se distribuyen como un plugin Wasm estándar de linter de publicación. Como las reglas viven en un plugin y no en el compilador, una empresa puede apuntar aggrega lint a otro plugin para imponer su propia disciplina de catálogo sin cambiar el compilador.

Un workspace puede adjuntar más de un linter bajo plugins.linter, y cada adjunto se ejecuta: en el orden en que están escritos los adjuntos, cada uno en su propia función de entrada, con todos sus hallazgos notificados juntos. Eso es lo que permite a un catálogo conservar las reglas estándar y añadir las suyas junto a ellas en lugar de elegir entre ambas. --plugin es la excepción — ejecuta exactamente un artefacto desde una ruta del sistema de archivos en lugar de los adjuntos configurados, lo que lo hace útil mientras se desarrolla una regla.

Una vinculación nombra su plugin con uri:, y function: nombra una función de entrada de ese plugin. Una entrada que nombra una function: y ningún uri: nombra una función de ningún plugin, así que la configuración se rechaza al leerse, con E0224, nombrando el archivo y la posición de la entrada en su lista — añade el uri del plugin que exporta la función. Una entrada que no nombra ninguno de los dos no vincula nada y se omite; cuando es la única entrada, el linter estándar se ejecuta con su propia función de entrada predeterminada, como ocurre sin ningún plugins.linter.

Qué recibe un plugin de linter

Ningún valor de parámetro llega a un plugin de linter, en ningún ámbito. El valor de un parámetro puede ser en sí mismo una credencial — el origin de un adjunto secreto puede ser una plantilla que lee un parámetro que la Release satisface, y el secreto es entonces el valor de ese parámetro — y el plugin que adjunta un workspace puede ser uno que no escribió, así que cada documento se entrega con sus valores de parámetros retenidos:

  • Un Aggregate conserva cada declaración de parámetro, manteniendo solo las claves con las que se escribe una declaración — el vocabulario de slots de parámetros: su tipo, su descripción y sus restricciones — y cada declaración anidada bajo sus properties, items y valuesType recibe el mismo trato. El default de la declaración se retiene en todos los niveles, eliminando la clave en lugar de vaciarla, de modo que un plugin no puede saber si una declaración da uno. Una clave fuera de ese vocabulario se retiene con todo lo que contenga, en todos los niveles: la build no da ningún significado a una clave así, y un borrador que escribe mal una clave puede llevar un secreto bajo ella. Una entrada bajo parameters que no es una declaración se retiene por completo.
  • Cada módulo listado bajo aggregates de un Aggregate pierde su bloque parameters, que contiene los valores pasados a ese módulo.
  • Una Release pierde su bloque parameters, tanto si escribe los valores en línea como si los importa con $import.
  • Cualquier otro documento que lleve un bloque parameters bajo spec lo pierde por completo; ningún otro tipo declara uno.

Esto se aplica a la entidad nombrada en la línea de comandos, a la versión publicada con la que --pre-publish la compara, a cada entidad que recorren las pasadas sobre todo el catálogo y con --release, y a los documentos que recibe una regla que lee una Release completa. Una plantilla que lee un parámetro no es un valor y conserva su texto, de modo que una regla sigue viendo qué parámetro lee un valor escrito por el autor.

Ejemplos

Recorrer todo el catálogo en busca de desviaciones de las convenciones:

aggrega lint --catalog ./catalog

Ejecutar el lint de una entidad en local mientras la escribes:

aggrega lint core/datastore/postgres/component.yaml

Ejecutar la puerta de publicación antes de publicar una nueva versión:

aggrega lint core/datastore/postgres/component.yaml --pre-publish

Relajar una regla para una sola ejecución:

aggrega lint core/datastore/postgres/component.yaml --pre-publish --allow-nonstandard-names

Véase también

  • ./aggrega-validate.md — la contraparte de corrección en los mismos tres ámbitos.
  • ./aggrega-build.md — valida como parte de la compilación; muestra el aviso de x-aggrega-* con severidad warn.
  • ./aggrega-push.md — publica una entidad en el registry; aggrega lint --pre-publish es la puerta que lo precede.
  • ./aggrega-pull.md — resuelve y fija las dependencias.
  • ./aggrega-serve.md — el language server que notifica estos hallazgos en tu editor, y el ajuste que activa la capa por edición.
  • ../errors/warnings.md — advertencias no fatales, incluidos los hallazgos de lint en modo local.

Sinopsis

aggrega lint [entity-path] [flags]

Descripción

aggrega lint checks publishing CONVENTIONS — naming, category-directory
alignment, annotation prefixes, and the rest of the publishing-linter
discipline. It does not check correctness (schema, pillars, resolution,
render): that is aggrega validate.
Three invocation shapes, mirroring validate:
aggrega lint conventions across every catalog entity
aggrega lint --release <path> conventions across a Release's dependency closure
aggrega lint <entity> publishing discipline for one entity
Without an entity argument, lint runs the structural conventions rules
over every catalog entity found under the catalog directories. Where the
workspace configuration gives its Releases catalog directories of their own
under workspace.releases, it runs them 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 it runs them over the entities that
Release's closure reaches, and also runs the rules that read a whole
Release: once, over the Aggregate it deploys, the Release and the
Components the Aggregate's components are instances of, with every
parameter value removed. In both, findings are advisory (warn severity)
and never halt.
With an entity path, lint runs the publishing-linter rule set against
that one entity. In default mode the rules run at warn severity over
local content without consulting any registry. With --pre-publish the
previous registry version is fetched and the schema-evolution
classification is compared against the proposed version bump; mismatches
halt. --pre-publish applies to the single-entity shape only. Per-workspace
policy flags from .aggrega-config.yaml's lint.publishing_discipline block
can be overridden per invocation via the --allow-*/--no-allow-* flag pairs,
in all three shapes.
All three shapes accept -o json, which replaces the human report on standard
output with one structured document: every finding with its severity, the rule
that produced it, its short code (the code printed at the head of its row in
the human report, which aggrega explain expands), its message, and the entity
file it concerns, plus counts by severity. A finding from a rule Aggrega does
not declare, one a linter of your own adds, carries no short code, as its row
prints none. A finding carries a line and column only when the rule that
produced it located the issue that precisely; otherwise the file alone locates
it. The message is the rule's own text, carried through unchanged, so the
structured and human renderings never word a finding differently. The exit
status is the same under either format.

Flags

FlagPredeterminadoDescripción
--allow-aggrega-ai-prefixfalseFuerza allow_aggrega_ai_prefix=true
--allow-category-mismatchesfalseFuerza allow_category_mismatches=true
--allow-connection-credential-mismatchesfalseFuerza allow_connection_credential_mismatches=true
--allow-direct-x-aggrega-extensionsfalseFuerza allow_direct_x_aggrega_extensions=true
--allow-dynamic-refsfalseFuerza allow_dynamic_refs=true para esta invocación
--allow-id-overridesfalseFuerza allow_id_overrides=true para esta invocación
--allow-nonstandard-namesfalseFuerza allow_nonstandard_names=true
--allow-undeclared-recipe-providesfalseFuerza allow_undeclared_recipe_provides=true
--baseline—Compara la comprobación de evolución previa a la publicación con esta versión concreta ya publicada en lugar de con la versión más alta seleccionada automáticamente por debajo de la que se publica; debe ser una etiqueta SemVer estricta presente en el registry (requiere —pre-publish)
--catalog[]Directorio de catálogo; repetible. Cada —catalog <dir> se antepone a la pila de búsqueda de catálogos (gana la primera coincidencia): los catalog_dirs del workspace o, para una Release a la que la configuración del workspace asigna directorios propios bajo 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. Lo usan las pasadas de convenciones sobre todo el catálogo y con —release.
--entity—Ruta al YAML de la entidad que se va a analizar con el lint (como alternativa, pásala como argumento posicional)
--no-allow-aggrega-ai-prefixfalseFuerza allow_aggrega_ai_prefix=false
--no-allow-category-mismatchesfalseFuerza allow_category_mismatches=false
--no-allow-connection-credential-mismatchesfalseFuerza allow_connection_credential_mismatches=false
--no-allow-direct-x-aggrega-extensionsfalseFuerza allow_direct_x_aggrega_extensions=false
--no-allow-dynamic-refsfalseFuerza allow_dynamic_refs=false para esta invocación
--no-allow-id-overridesfalseFuerza allow_id_overrides=false para esta invocación
--no-allow-nonstandard-namesfalseFuerza allow_nonstandard_names=false
--no-allow-undeclared-recipe-providesfalseFuerza allow_undeclared_recipe_provides=false
--output, -otextFormato de salida: text|json.
--plugin—Ruta del sistema de archivos al artefacto .wasm del linter de publicación (ejecuta este artefacto en lugar de los adjuntos plugins.linter del workspace)
--pre-publishfalseObtiene la versión anterior del registry y verifica el incremento propuesto frente a la clasificación de evolución del esquema
--release—Ruta a un YAML de Release cuyas convenciones se comprueban sobre el cierre de sus dependencias resueltas (mutuamente excluyente con un argumento de entidad). Una ruta relativa se resuelve respecto al directorio en el que ejecutas el comando, no respecto a la raíz del workspace. Cuando ese directorio no está en ningún workspace y no se indica ninguna raíz, una ruta absoluta encuentra el workspace a partir de la propia carpeta de la Release