aggrega build
aggrega build compile une paire Aggregate + Release en artefacts natifs des providers (manifestes Helm, charts Helm redistribuables, YAML docker-compose) sous dist/ à la racine du workspace, comme l’expose Sortie. La Release est le point d’entrée unique : elle nomme l’Aggregate et le Manifest, déclare les frontières et achemine les composants vers les providers.
Options courantes
Deux options ont un comportement que la référence des options ci-dessous ne peut pas transmettre à elle seule :
--catalog <dir>— un répertoire contenant des entités de catalogue — les types d’écriture Component, Feature, Recipe et FeatureRecipe ainsi que les types de bibliothèque, les Aggregates et les Plugins —, chargé récursivement. Chaque répertoire--catalogest parcouru avant les répertoires configurés, dans l’ordre indiqué. Pour parcourir un catalogue local au projet en plus d’un catalogue partagé, passez les deux (--catalog ./catalog --catalog ../shared-catalog) ou listez-les souscatalog_dirs. Avec--detail, toute entité masquée par un répertoire de priorité supérieure est signalée sur stderr, avec les autres avertissements du build. Un répertoire--catalogqui n’existe pas arrête le build, en le nommant. Il en va de même d’un répertoire listé souscatalog_dirsqui n’est pas un répertoire, avant que quoi que ce soit ne soit lu ou écrit, en nommant l’entrée ainsi que le fichier de configuration et la ligne qui la listent — voir D’où les entités locales sont lues. Un build qui s’arrête parce qu’une référence ne s’est résolue en rien nomme, dans la note sous l’arrêt, chaque fichier de ces répertoires qui déclare une apiVersion Aggrega — une ligne commençant, sans indentation, parapiVersion:avec une valeur débutant paraggrega.ai/— et n’a pas pu être chargé, par exemple un fichier qui ne s’analyse pas comme du YAML, avec la raison donnée par l’analyseur lui-même, parmi les fichiers de catalogue ignorés au chargement ; un fichier YAML qui déclare une autre apiVersion, ou aucune, n’est pas un document Aggrega et n’y est jamais nommé.--detail— indique ce qu’a fait l’étape de pull, le même diagnostic transitoire des événements de pull qu’émetaggrega pull --detail. Ce qui décide s’il y a quelque chose à signaler, c’est si une étape de pull a été demandée — avec--auto-pull, ou en activantauto_pull— et non si un lockfile est déjà présent : une étape de pull demandée s’exécute dans les deux cas, en remplissant un lockfile manquant et en respectant les pins d’un lockfile existant. Lorsqu’aucune étape de pull ne s’exécute, l’option affiche une note d’une ligne sur stdout et poursuit — elle n’invente jamais un niveau de résolution que le lockfile commité ne contient pas. Pour l’état de résolution après pull des dépendances d’une Release, utilisezaggrega inspect.
--dry-run est traité dans Prévisualiser un build sans l’écrire, et --trace et --trace-unredacted dans Sortie de trace et Afficher les valeurs masquées ci-dessous.
Remplir le lockfile dans le cadre du build
Par défaut, le build est en lecture seule vis-à-vis des dépendances : il a besoin d’un lockfile et n’en écrit aucun. --auto-pull, ainsi que le paramètre de workspace auto_pull, ajoutent l’étape de pull au build, de sorte qu’une seule commande résout les dépendances de la Release et compile à partir de ce qu’elle a résolu.
Une modification de la Release est quelque chose que le lockfile remarque. Le lockfile enregistre la Release — et chaque Release qu’elle étend — par le digest de son contenu, si bien qu’un build en lecture seule sur une Release modifiée depuis le pull s’arrête avant tout rendu, en nommant le fichier et en vous indiquant d’exécuter aggrega pull --release <release>, qui enregistre la modification tout en respectant tous les autres pins. Un commentaire ou une modification d’espaces compte, car le digest couvre les octets tels qu’ils sont. Un build avec auto-pull exécute lui-même cette étape de pull, il enregistre donc la modification et effectue le build.
La Release est rendue une seule fois. Les entrées externes qu’une Release consomme découlent de son rendu plutôt que de ce que déclarent ses documents ; l’étape de pull effectue donc le rendu de la Release pour le découvrir — et ce rendu est celui du build. Un build avec auto-pull coûte donc un seul rendu, autant qu’un build simple sur un lockfile déjà en place.
Les options qui façonnent un rendu s’y appliquent. --trace, --verify-determinism, --disable-plugin-cache et --no-unsupported-field-warnings atteignent le rendu qu’effectue un build avec auto-pull dans les mêmes conditions que celui d’un build simple, de sorte que demander une trace ou une vérification de déterminisme sur un build en une seule commande vous l’obtient. --dry-run est l’exception, et il s’agit d’un refus plutôt que d’un silence : un dry run n’écrit rien alors que l’étape de pull écrit, donc la combinaison s’arrête avant tout travail (voir Prévisualiser un build sans l’écrire).
Comment un build lit ce que le lockfile épingle
Un pin du lockfile désigne un contenu — un digest — plutôt qu’un emplacement. Pour une entité, c’est le digest de ce que contient une publication de celle-ci, son document et les fichiers qu’il nomme, si bien qu’une copie d’une entité dans un répertoire de catalogue et une entrée du cache contenant sa publication portent le même pin, comme le décrit Le lockfile. Un build lit chaque dépendance épinglée à partir des sources déjà présentes sur la machine : d’abord les répertoires de catalogue, comme partout ailleurs, puis le cache de contenu sous .aggrega/cache. Les lire n’interroge aucun registre ; seule l’étape de pull, lorsqu’un build en exécute une, télécharge.
Une entrée du cache qui ne contient plus son pin est ignorée. Une entité modifiée sur place — un nouveau corps sous la même version — laisse dans le cache de contenu le corps antérieur sous ce nom et cette version. Lorsqu’un répertoire de catalogue contient une copie dont le contenu a pour digest le pin, le build lit cette copie et jamais l’entrée, et il le signale sur la sortie d’erreur standard, en nommant l’entrée et les deux digests :
reuse: cache entry for <name>:<version> holds <digest the entry holds>, not the pinned <pinned digest>; passed over for <catalog file>, which holds the pinned bytesLorsqu’aucun répertoire de catalogue ne contient l’entité, une entrée du cache complète contenant exactement les octets épinglés est lue comme la dépendance, si bien qu’une entité retirée de son répertoire de catalogue après le téléchargement de sa copie publiée se construit toujours à partir de cette copie.
Lorsqu’aucune source ne contient les octets épinglés, le build s’arrête avant tout rendu, avec E0135 — ou E0133 lorsque le manifeste de l’entrée du cache n’est pas celui qu’épingle le lockfile. L’arrêt nomme le pin, l’entrée du cache et le digest qu’elle contient, ainsi que chaque copie de l’entité dans un répertoire de catalogue avec son digest, ou indique qu’aucun répertoire de catalogue ne la contient. Le remède est un pull avec un registre joignable, qui télécharge à nouveau la version épinglée et vérifie ce qu’il télécharge par rapport au pin ; voir Respecter ou mettre à jour pour ce que fait le pull lorsque le registre ne sert plus ces octets.
Le rendu qu’exécute aggrega pull pour découvrir les entrées externes, ainsi qu’un build ou un aperçu via aggrega serve ou aggrega mcp, lisent leurs pins de la même manière.
Entrées externes au moment du build
Un rendu peut demander du contenu depuis une URL distante — le schéma des valeurs d’un chart avec une référence distante, par exemple — et un build n’en télécharge jamais une pour l’ajouter à ce que le rendu peut lire. Une demande portant sur une URL que le lockfile épingle déjà est servie depuis le stockage des entrées du workspace et vérifiée par rapport au digest enregistré avant qu’un seul octet n’atteigne le rendu. Une demande portant sur une URL non épinglée s’arrête, en nommant l’URL et l’étape qui l’épingle ; aucun paramètre ne transforme cet arrêt en téléchargement, car élargir discrètement l’ensemble des entrées que lit un build est la seule chose qu’un build reproductible ne doit pas faire.
Lorsque la copie d’une entrée épinglée dans le stockage a disparu, cette seule entrée est téléchargée à nouveau par le digest que le lockfile enregistre déjà, et vérifiée par rapport à celui-ci avant que quoi que ce soit ne soit écrit ou renvoyé. Cela ne peut pas changer ce que voit le rendu — le digest a été fixé lorsque l’entrée a été épinglée — donc cela répare le stockage plutôt que d’étendre la fermeture, et le lockfile reste inchangé à l’octet près. En mode hors ligne, il n’existe aucun transport même pour cela, et la copie manquante provoque plutôt un arrêt, qui nomme le mode.
L’épinglage a lieu lorsque les dépendances de la Release sont résolues, de sorte que ce qu’un build peut lire est établi avant que le build ne commence. aggrega pull est cette étape, et c’est la seule.
L’enregistrement de confiance des plugins
Plusieurs comportements d’un build dépendent de plugins-trust.yaml, le fichier commité à côté du lockfile de la Release qui enregistre vers quel plugin chaque rattachement renvoyant un verdict s’est résolu — un rattachement plugins.governance dans un rôle ir-verdict ou render-verdict, et chaque rattachement plugins.linter. aggrega pull l’écrit et le schéma de l’enregistrement de confiance des plugins décrit ses champs ; ce qui suit porte uniquement sur ce qu’un build en fait lui-même.
Un build est confronté à l’enregistrement avant qu’aucun de ces plugins ne s’exécute. Un plugin servi depuis le cache dont le digest d’artefact n’est pas celui enregistré est refusé plutôt qu’exécuté — c’est la résolution que prend normalement un tel rattachement, et aggrega pull expose quelles autres manières d’en résoudre un ne sont pas régies par le digest enregistré. Et une entrée enregistrée dont plus aucun rattachement de .aggrega-config.yaml ne rend compte arrête le build : supprimer un contrôle ne change aucun octet rendu, si bien qu’une sortie produite sans un contrôle révisé ressemble exactement à une sortie que ce contrôle a approuvée. L’arrêt nomme le plugin et propose les deux remèdes qui diffèrent selon ce que vous vouliez — le rattacher à nouveau si la suppression était une erreur, ou demander explicitement la suppression si ce n’en était pas une — et il affiche la commande prête à exécuter. Un rattachement que l’enregistrement ne contient pas encore est une première apparition, et aucune des deux comparaisons ne s’arrête sur lui.
Un build confronte chacun de ces plugins à la signature qu’enregistre son entrée, exactement comme il confronte une entrée du lockfile à celle qu’enregistre cette entrée. Lorsqu’une entrée enregistre une signature vérifiée, le build recalcule, avant tout rendu, le hachage du bundle de signature que ce fait nomme dans le cache, et s’arrête avec E0144 lorsque le bundle est absent ou diffère. Pour un plugin qu’il lit depuis le cache de contenu, il lit aussi dans ce bundle pour quel artefact la signature a été faite, et s’arrête avec E0332 lorsqu’elle a été faite pour un autre plugin que celui que le build a lu — ce à quoi ressemble une signature copiée depuis une autre entrée — quoi que dise l’exigence de signature. Pour un plugin servi par le cache de contenu, l’un et l’autre refus nomment aggrega pull --release <release> : le pull suivant vérifie à nouveau la signature du plugin, enregistre celle du plugin lui-même et met en cache le bundle qu’elle nomme, en réécrivant une copie en cache qui ne correspond plus à son digest. Lorsque la configuration de confiance du workspace exige une signature pour un plugin que le build lit depuis le cache de contenu — selon les mêmes paramètres qui feraient refuser à aggrega pull ce plugin non signé, de sorte que skip_signature_verification et un registre advisory laissent le build continuer comme ils laissent continuer le pull — une entrée n’enregistrant aucune signature, ou l’absence de toute entrée pour le plugin, arrête le build avec E0331, en nommant le plugin, plugins-trust.yaml et les paramètres qui exigent la signature. Le remède est aggrega pull --release <release>, qui vérifie la signature du plugin auprès de son registre à chaque exécution et l’enregistre. Un plugin servi depuis l’un de vos répertoires de catalogue, ou depuis la copie incluse dans le binaire du compilateur, n’est jamais soumis à cette exigence. Comme le reste du build, cela lit des fichiers déjà présents sur la machine et n’interroge aucun registre.
Un build nomme chaque retrait que contient l’enregistrement, à côté de chacun de ceux que contient le lockfile. Un marqueur que aggrega pull a enregistré pour l’un de ces plugins est signalé par une ligne deprecation: nommant le plugin, la sévérité enregistrée et le message de l’éditeur, quelle que soit la sévérité, et build.halt_on_deprecated_severity décide s’il arrête aussi le build, selon la même règle qu’il applique à une référence épinglée. Toutes les autres surfaces qui rendent compte d’une Release nomment le même ensemble dans les mêmes termes, et aucune ne s’arrête pour autant : aggrega validate --release, aggrega lint --release, aggrega inspect --closure, la validation et la réponse de clôture du serveur de langage, et les outils describe et validate de l’assistant. Un enregistrement présent mais illisible arrête le build au lieu de passer pour un enregistrement qui ne contient rien.
aggrega build --upgrade réécrit ce fichier. Elle implique --auto-pull et exécute un rafraîchissement complet sans argument, qui résout à nouveau chaque dépendance et donc résout à nouveau et réécrit chaque identité enregistrée, et supprime chaque entrée dont aucun rattachement ne rend compte. Si ce fichier apparaît modifié après un build de mise à niveau, voilà pourquoi : la portée de l’option est chaque dépendance, et les identités enregistrées font partie de ce qui est résolu à nouveau, même si ce ne sont pas des pins du lockfile. Contrairement à aggrega pull --upgrade, l’option du build ne prend pas de cible, elle ne peut donc pas être restreinte à un seul plugin : pour adopter ou supprimer une seule identité, exécutez plutôt aggrega pull --upgrade --release <release> <plugin>, qui laisse intacts tous les autres pins et toutes les autres identités enregistrées.
Comme sa portée est totale, elle demande confirmation avant de commencer. aggrega build --upgrade confirme le rafraîchissement dans les mêmes conditions que le aggrega pull --upgrade sans argument — les deux sont le même acte, ils posent donc la même question. Passez --yes pour répondre à l’avance en usage non interactif ; si l’entrée standard n’est pas un terminal et qu’il n’y a pas de --yes, le build refuse plutôt que d’attendre une réponse que personne ne peut donner. Un build qui ne rafraîchit pas ne demande rien.
Résolution du workspace et déterminisme
La référence manifest: de la Release, requise par le schéma, est résolue par rapport au fichier de la Release. Une entrée catalog_dirs relative (et un chemin relatif de plugin sur le système de fichiers) est résolue par rapport au répertoire du .aggrega-config.yaml qui l’a déclarée — « relatif » signifie toujours relatif au fichier dans lequel vous l’avez écrit, si bien qu’un chemin a le même sens quel que soit l’endroit d’où vous invoquez aggrega. Une option --catalog, qui n’a pas de fichier déclarant, est résolue par rapport au répertoire de travail courant. Les références de registre (oci://…, une référence de hub) sont laissées telles quelles.
La racine du workspace est le répertoire du .aggrega-config.yaml ancêtre le plus proche qui porte un bloc workspace:, ou le répertoire que nomme --workspace-root. Lorsque la racine est ainsi fixée, un build est indépendant du lieu d’invocation : exécuter aggrega build depuis la racine du projet et depuis un sous-répertoire produit un IR et des artefacts rendus identiques à l’octet près, car le catalogue parcouru et les chemins source enregistrés dans la sortie ne changent pas avec le répertoire de travail. (Sans marqueur workspace: ni --workspace-root, le répertoire de travail est la racine, et la sortie y est donc ancrée — sauf si le répertoire de travail n’ancre rien et que --release nomme la Release par un chemin absolu : la racine est alors découverte à nouveau à partir du dossier de la Release elle-même, de sorte que le catalogue parcouru et les chemins enregistrés dans la sortie sont ceux du projet auquel appartient la Release, quel que soit l’endroit d’où vous exécutez la commande. Voir configuration.md.) Lorsqu’aucun workspace n’est trouvé de cette manière non plus et que rien n’en nomme un, le build avertit sur la sortie d’erreur standard que le dossier qu’il a utilisé comme racine ne se trouve dans aucun workspace, et nomme la commande qui en fait un ; un build à qui il est demandé de résoudre d’abord ses dépendances est refusé avant tout téléchargement, car le cache que cette résolution remplit serait écrit dans ce dossier et en ferait un workspace. Un build qui ne résout rien au préalable effectue tout de même le rendu, mais pour la même raison, une entrée externe que le lockfile épingle et que le cache ne contient plus n’est pas téléchargée à nouveau : le plugin qui la demande reçoit à sa place la phrase du refus, comme il reçoit celle du mode hors ligne, et le build rapporte ce que ce plugin en fait. Un --workspace-root ou un AGGREGA_WORKSPACE_ROOT nommant un dossier inexistant est refusé avant que le build ne fasse quoi que ce soit d’autre, en nommant celui des deux qui l’a fourni.
Variables d’environnement
Les paramètres de workspace que lit le build peuvent être remplacés via l’environnement, au-dessus de la configuration commitée et en dessous de toute option : AGGREGA_OFFLINE, AGGREGA_AUTO_PULL, AGGREGA_CATALOG_DIRS (séparés selon la liste de chemins du système d’exploitation ; fournissez des chemins absolus), AGGREGA_ARTIFACT_CACHE_DIR, AGGREGA_DEFAULT_REGISTRY et AGGREGA_WORKSPACE_ROOT. Voir environment-variables.md pour la liste complète et le modèle de priorité.
Sortie
Les artefacts rendus sont placés sous dist/ à la racine du workspace, quel que soit le dossier depuis lequel la commande est exécutée — la racine elle-même, un dossier en dessous, ou un dossier ailleurs avec la racine nommée par --workspace-root ou AGGREGA_WORKSPACE_ROOT — et la ligne finale nomme ce répertoire en entier :
Build completed: 4 files written to <workspace>/dist<workspace> désigne ici la racine du workspace, que la ligne écrit sous forme de chemin complet. Lorsqu’aucun workspace n’est trouvé et que rien n’en nomme un, le dossier depuis lequel la commande a été exécutée est la racine, et dist/ y est donc écrit. Un dist qui est un lien menant hors du workspace est refusé avant que quoi que ce soit à l’intérieur ne soit supprimé ou écrit. Une Release qui ne déclare aucune frontière écrit par provider : dist/<provider>/<files>. Une frontière déclarée sans directory: écrit par frontière et par provider : dist/boundaries/<boundary-path>/<provider>/<files>. Les surcharges directory: et subDirectory: rédigées par l’opérateur sur les frontières de la Release modifient le chemin cible ; la fusion par (path, provider) regroupe les contributeurs qui se résolvent vers le même chemin évalué.
Fichiers que le build n’a pas écrits
Un build écrit ses propres fichiers et ne supprime rien qu’il n’a pas écrit, à une exception près : dist/boundaries/, qu’un build régénère entièrement, est vidé avant l’écriture, de sorte qu’un fichier laissé là par un build d’une autre variante ne survit pas dans une arborescence qui ne le produit plus. Tout le reste de dist/ est laissé tel quel — un fichier écrit par un build antérieur que celui-ci ne produit plus, un fichier que le directory: d’une boundary y a placé lors d’une exécution antérieure, et un fichier que vous y avez mis vous-même, sans distinction —, car le build ne peut pas distinguer un reste d’un fichier que vous y conservez volontairement.
Ce qu’il fait à la place, c’est vous le dire. Une fois ses fichiers écrits, le build examine dist/ lui-même et chaque répertoire en dessous dans lequel il a écrit un fichier ou qu’il a traversé pour en écrire un plus profond, et nomme chaque fichier qui s’y trouve et qu’il n’a pas écrit lors de cette exécution, dans un unique avertissement sur la sortie d’erreur standard. Les fichiers sont nommés par leurs chemins relatifs à dist/, triés, de sorte que la même arborescence est signalée de la même façon à chaque exécution :
warning: the output directory holds 2 file(s) this build did not write, in directories it wrote into; nothing was removed, so they sit beside this build's output: "app/stale-from-earlier-run.yaml", "beside-the-tree.txt"La ligne de clôture les compte ensuite :
Build completed: 1 file written to <workspace>/dist, beside 2 files this build did not writeUn répertoire dans lequel le build n’a rien écrit, ni directement ni plus bas, n’est pas examiné, de sorte qu’un dossier à vous conservé sous dist/ n’est pas listé fichier par fichier. Un build qui ne trouve aucun fichier de ce genre n’affiche aucun avertissement, et sa ligne de clôture est celle présentée sous Sortie. Dans les deux cas, les fichiers que le build écrit sont les mêmes octets. Pour comparer deux builds, ou pour repartir de zéro, supprimez dist/ avant de lancer le build.
La requête aggrega/build de aggrega serve et l’outil build de l’assistant (aggrega mcp) écrivent par la même étape, et nomment donc les mêmes fichiers dans la même phrase : le démon comme l’un des notices de sa réponse, et l’outil comme le dernier de ses advisories. Une exécution à blanc n’écrit rien, et ne signale donc rien de tout cela.
Indentation YAML
Chaque artefact YAML rendu — fichiers docker-compose, templates et valeurs de charts Helm, et manifestes Kubernetes — est émis avec une largeur d’indentation uniforme. La largeur est définie par build.yaml_indent dans .aggrega-config.yaml et vaut 2 par défaut (la largeur conventionnelle pour ces formats) :
build: yaml_indent: 2 # default; accepts 2 through 9La largeur est appliquée en un unique point de sérialisation partagé par tous les moteurs de rendu, de sorte que la sortie reste identique à l’octet près d’une exécution à l’autre sur la même entrée. Les valeurs hors de la plage [2, 9] sont rejetées par la validation du schéma de configuration.
Restituer le graphe compilé
--ir-graph écrit sur la sortie standard, en JSON, le graphe que ce build a résolu. Elle est additive : les artefacts sont toujours écrits dans dist/, le résumé est toujours affiché et les octets rendus sont inchangés. Le graphe sort avant tout ce que le build y affiche d’autre — un document JSON et un saut de ligne final — de sorte qu’un consommateur qui décode le flux le lit et s’arrête.
Le graphe restitué est celui que le rendu a consommé ; il décrit donc exactement le build qui a produit les artefacts qui l’accompagnent plutôt qu’une seconde résolution de la même Release. Elle se combine avec --dry-run : le graphe est écrit et le rapport des artefacts le suit, sans rien écrire sur le disque.
Les valeurs qu’un auteur a déclarées sensibles y sont masquées — y compris les values et infra d’une connexion, lorsque le socket du composant consommateur déclare une feuille sensible —, sous la forme structurée décrite dans aggrega inspect. --unredacted à côté de --ir-graph les affiche à la place, dans les conditions qu’énonce aggrega inspect --unredacted : elle atteint le graphe et rien d’autre — les fichiers de trace ont leur propre --trace-unredacted, et les artefacts rendus ne sont jamais masqués — et tout ce que la sortie atteint contient alors ces valeurs en clair. Passée sans --ir-graph, elle est refusée, car elle n’aurait rien à révéler.
La même option, avec le même sens, existe sur aggrega inspect et aggrega validate.
Prévisualiser un build sans l’écrire
--dry-run exécute la même compilation qu’un build — les mêmes contrôles de dépendances, le même rendu, les mêmes providers — et affiche ce qu’il émettrait au lieu de l’écrire. Chaque artefact est indiqué avec le chemin qu’il occuperait et le contenu qu’il aurait :
aggrega build --release releases/production.yaml --dry-run==> <workspace>/dist/main/helm/webapp-configmap-webapp.yaml <==apiVersion: v1kind: ConfigMap...
Total build time: 2.5sDry run: 1 file would be written to <workspace>/dist; nothing was writtenLes artefacts sont indiqués dans l’ordre dans lequel un build les écrit, de sorte que la même entrée indique les mêmes octets dans la même séquence, et le chemin indiqué est celui dans lequel un build écrirait — sous la racine du workspace, écrit en entier là où figure <workspace> ci-dessus.
Ce qui n’est pas écrit. Le répertoire de sortie reste exactement tel qu’il est — il n’est pas nettoyé non plus, de sorte que la sortie d’un build précédent survit intacte à un dry run. Le lockfile n’est pas écrit. Rien n’est écrit dans .trace/.
Les entrées externes se comportent exactement comme dans un build ordinaire, dans les conditions qu’expose Entrées externes au moment du build. Un dry run lit donc la même fermeture épinglée que lirait le build qu’il représente, et ce qu’il montre est ce que ce build écrirait.
Lorsqu’une référence a été refusée, l’exécution nomme chacune de celles qu’elle n’a pas pu atteindre et indique la commande qui les épingle :
note: the lockfile does not pin every external reference this render requested, so the following were declined and the render stopped short of the artifacts it would otherwise emit: - https://charts.example.com/values-schema.json Run `aggrega pull --release releases/production.yaml` to pin the inputs the render needs, then run the dry run againExécutez aggrega pull une fois et le dry run dispose de tout ce dont il a besoin ; rien d’autre ne change pour lui.
Un dry run a besoin d’un lockfile et n’en remplit jamais. Le build est en lecture seule par défaut, et un dry run s’y tient quelle que soit la manière dont un remplissage a été demandé. --auto-pull et --upgrade sont refusées purement et simplement (ci-dessous) ; le paramètre de workspace auto_pull est outrepassé pour cette seule invocation, de sorte qu’un workspace qui remplit par défaut peut tout de même être prévisualisé. Sans lockfile, un dry run s’arrête avec le même remède qu’un build ordinaire en lecture seule : exécutez d’abord aggrega pull.
Les options qu’il refuse. Trois options écrivent ; les combiner avec un dry run n’a donc aucune issue honnête — ignorer l’écriture ferait disparaître un remplissage demandé, et la respecter romprait la seule promesse que fait le dry run. Chaque combinaison s’arrête avant tout travail, en nommant l’option passée et l’étape à exécuter à la place :
| Combinée avec | Raison du refus |
|---|---|
--auto-pull | remplit le lockfile ; exécutez aggrega pull comme étape distincte |
--upgrade | résout à nouveau chaque dépendance et réécrit le lockfile ; exécutez aggrega pull --upgrade comme étape distincte |
--trace | écrit des fichiers par nœud dans .trace/ ; exécutez le build tracé sans --dry-run |
Tout le reste se combine normalement. --verify-determinism effectue le rendu de chaque nœud deux fois et compare les octets sans en écrire aucun, et --catalog, --quiet, --progress, --debug ainsi que les filtres d’avertissements se comportent exactement comme sur un build qui écrit.
À quoi il sert, et à quoi il ne sert pas. Un dry run répond à « qu’émettrait cette Release », une question à laquelle seul un rendu peut répondre — il ne remplace donc ni aggrega validate, qui vérifie l’exactitude sans rendu, ni aggrega inspect, qui interroge le graphe avant le rendu. Recourez à un dry run lorsque la réponse que vous voulez, ce sont les artefacts eux-mêmes : examiner ce qu’une modification de la Release fait à la sortie, ou vérifier une modification de Recipe avant de valider quoi que ce soit dans dist/.
Sortie de trace
L’option --trace active un dump de débogage par nœud qui capture chaque état intermédiaire du compilateur. La sortie se trouve dans .trace/ sous la racine du workspace, à côté de dist/ (jamais en dessous ; la disposition côte à côte suit la convention de .git/, .terraform/, node_modules/ et garde dist/ purement déployable).
L’arborescence des répertoires est organisée par frontière et par instance :
.trace/└── boundaries/ └── <boundary-path>/ └── <instance-id>/ ├── 01-pillars-initial.yaml ├── 02-provides-evaluation.yaml ├── 03-inject-hydration.yaml ├── 04-inject-mapping.yaml ├── 05-source-resolution.yaml ├── 06-source-locals.yaml ├── 07-values-mapping.yaml ├── 08-workload-synthesis.yaml ├── 09-artifact-evaluation/ │ └── <per-artifact-file>.yaml ├── 09b-feature-rendering-boundary.yaml ├── 10-engine-synthesis/ │ └── <per-synthesized-file>.yaml ├── 11-engine-emission.log └── 12-labels-injected.logChaque emplacement capture un état précis du compilateur :
01-pillars-initial.yaml— l’instantané par nœud du contexte que lit un template, pris après la résolution et avant toute mutation par étape. Contient.values,.infra,.context,.parameters,.metadata.02-provides-evaluation.yaml— les sortiesprovides:résolues après l’évaluation des provides.03-inject-hydration.yaml— le pipe.context.injectfusionné après l’hydratation des injections (vue côté consommateur desprovidesen amont).04-inject-mapping.yaml— le pipe.context.injectaprès les réécrituresinjectMappingde la FeatureRecipe.05-source-resolution.yaml— le contenusource:analysé que le provider consommera. Présent uniquement lorsque la Recipe déclaresource:.06-source-locals.yaml— le bloclocals:résolu. La résolution de la source publie.localsavant d’évaluer le templatesource:, c’est pourquoi cet emplacement est écrit que la Recipe déclaresource:ou non.07-values-mapping.yaml— la sortie rendue devaluesMapping:(le dictionnaire que reçoit le provider). Présent uniquement lorsque la Recipe déclarevaluesMapping:.08-workload-synthesis.yaml— le contexte tel qu’il était lorsque le templateworkload:a été évalué et sa sortie analysée. Présent uniquement lorsque la Recipe déclareworkload:(en ligne ou chargé via$import:). LeWorkloadanalysé lui-même ne figure pas dans cet emplacement : il apparaît à partir de09-artifact-evaluation/, une fois établi plutôt qu’en cours.09-artifact-evaluation/— un fichier par artefact évalué. Présent uniquement lorsque la Recipe déclareartifacts:(avec des entrées en ligne ou chargées entrée par entrée via$import:).09b-feature-rendering-boundary.yaml— le contexte tel qu’il se présente à la fin du rendu du nœud, une fois que les FeatureRecipes qui y sont attachées ont généré leurs ressources, avec leworkloadanalysé à côté. Écrit pour chaque nœud.10-engine-synthesis/— un fichier par manifeste synthétisé que le provider a produit à partir du Workload (mode workload de helm/compose). Présent uniquement lorsque le provider a suivi un chemin de synthèse.11-engine-emission.log— le résumé post-émission (nombre de fichiers, chemins de sortie) pour le nœud.12-labels-injected.log— les labels et annotations de provenance écrits sur la sortie rendue pour le nœud.
À partir de 03-inject-hydration.yaml, un emplacement qui montre le contexte du nœud contient le bloc .context.inject dès que le pipe qu’il capture livre au moins une clé, par quelque mécanisme que ce soit : env, file, arg, ou un mécanisme d’un autre nom dans lequel écrit un mapping inject, l’injectMapping d’une FeatureRecipe ou le propre bloc inject: du composant. Un nœud dont la seule livraison passe par un tel mécanisme personnalisé montre lui aussi le bloc, avec ce mécanisme sous son propre nom et ses clés dans all, et une valeur déclarée sensible se lit comme <redacted> aux deux endroits. Un emplacement capturé alors que le pipe ne livre rien n’a pas de bloc .context.inject.
L’écrivain de trace est non bloquant : la trace est écrite sur le disque parallèlement à la compilation plutôt que sur son chemin. La latence de compilation n’est pas affectée par les E/S de trace — la même compilation se termine dans le même temps réel, que --trace soit activée ou non.
Valeurs déclarées sensibles dans la trace
Une donnée qu’un auteur a déclarée sensible — une feuille de schéma portant sensitive: true, ou une clé de livraison dont le matériau provient d’une clé provides qui le porte — est écrite dans la trace sous la forme du texte fixe <redacted>. La clé est conservée et seule la valeur est remplacée, de sorte qu’un emplacement montre toujours quelles feuilles et quelles clés de livraison porte un nœud. Un élément voisin non déclaré dans le même bloc affiche sa valeur telle quelle ; la substitution suit la déclaration et rien d’autre.
Une valeur qu’une FeatureRecipe livre par son propre injectMapping est également masquée. C’est la voie à laquelle un emplacement déclarant une liste inject vide confie la livraison, et la voie que prend une réalisation d’identifiants uniquement par injection. La clé de livraison qu’écrit un tel mapping est elle-même un template, si bien qu’aucune déclaration ne la nomme ; c’est le texte même du mapping qui est lu à la place. Lorsque ce texte référence une feuille values ou infra que la Feature rattachée déclare sensitive: true, chaque clé de livraison produite par le mapping se lit comme <redacted> — y compris une clé qui ne contient rien de sensible, puisque la lecture se fait par rattachement plutôt que par clé. Un mapping qui ne référence rien de déclaré affiche ses clés telles quelles.
Une valeur qu’un template a calculée à partir d’une donnée déclarée sensible est également masquée, même si sa propre clé ne porte aucune déclaration. Ce qui l’identifie, c’est la référence écrite par l’auteur : une entrée locals: dont le template lit une feuille déclarée sensible est masquée, de même qu’un champ source: qui le fait. La lecture est prudente — un template qui atteint un objet entier atteint chaque feuille déclarée sous celui-ci, si bien que {{ range $k, $v := .values.creds }} masque sa sortie lorsque quoi que ce soit sous creds est déclaré — et une entrée locals: qui lit un voisin déjà masqué est masquée à son tour. Une entrée voisine de même forme qui ne lit rien de déclaré s’affiche telle quelle.
Une valeur qui transite par une arête uses est masquée selon les déclarations de la cible, et non du nœud consommateur, et elle est masquée sur les deux surfaces vers lesquelles l’arête la porte. .context.uses.<alias>.provides reproduit ce que le composant cible a publié, de sorte que ce qui régit ces valeurs est le schéma de la cible : une clé provides que la cible a déclarée sensible se lit comme <redacted> dans l’emplacement du consommateur, même lorsque le consommateur ne déclare rien du tout. Lorsque le bloc inject propre à l’arête achemine cette clé vers une clé de livraison du composant consommateur, .context.inject masque aussi cette clé de livraison — la même règle que suit déjà le mapping inject d’un rattachement, en lisant la même déclaration. Le masquage se fait par arête, si bien que deux arêtes publiant le même nom de clé provides se résolvent indépendamment : celle dont la cible l’a déclarée est masquée et l’autre s’affiche telle quelle. Le reste de l’arête — sa cible, son socket, ses labels et les noms de clés propres au mapping inject — n’est pas ce que régit une déclaration provides de la cible, et s’affiche tel quel.
Les values et infra par connexion rédigés sur l’arête elle-même sont régis à la place par le socket du composant consommateur : le valueSchema et l’infraSchema que ce socket déclare, qui sont les contrats selon lesquels cette configuration est validée. Une feuille que l’un ou l’autre contrat déclare sensitive: true se lit comme <redacted> à .context.uses.<alias>.values ou .context.uses.<alias>.infra, la clé étant conservée, et il en va de même d’une feuille qui se trouve à une valeur par défaut déclarée par le contrat ; un élément frère non déclaré s’affiche tel quel. Les déclarations de la cible ne jouent ici aucun rôle, et le masquage se fait par connexion, si bien qu’une feuille du même nom sur une connexion dont le socket la déclare lisible s’affiche telle quelle.
Les rattachements écrits sur une connexion sont affichés sous l’arête de cette connexion, à .context.uses.<alias>.features.<slot>, et chacun est masqué selon les déclarations de sa propre Feature — les mêmes qui régissent cette Feature lorsqu’un composant la détient directement. Une feuille values ou infra que la Feature déclare sensitive: true se lit comme <redacted>, de même qu’une clé des provides résolus du rattachement que la Feature déclare sensible ; chaque clé est conservée. Le type, la version et les labels du rattachement, ainsi que chaque feuille et chaque clé provides que sa Feature laisse non déclarée, s’affichent tels quels, de sorte qu’un localisateur publié reste lisible à côté du matériau qu’il localise. Le masquage se fait par connexion et par emplacement, si bien que la même Feature écrite sur deux connexions se résout sur chacune. Un emplacement qui déclare sensitive: true — sur le composant ou sur son socket — indique que le rattachement manipule du matériau secret et ne masque aucune feuille de lui-même : c’est à la Feature de déclarer quelles feuilles sont masquées. Les rattachements propres d’un composant ne font pas partie des blocs qu’affiche un emplacement, puisque la trace ne contient aucun bloc .features ; ce qu’un template workload: lit dans l’un d’eux est couvert par le nouveau rendu décrit ci-dessous.
Le Workload analysé est un nouveau rendu, et non une capture du document émis par le build, et les emplacements qui le portent — 09-artifact-evaluation/, 10-engine-synthesis/ et 09b-feature-rendering-boundary.yaml — l’indiquent dans une entrée workload_note à côté de lui. Un document rendu n’enregistre rien sur la déclaration dont provient un caractère donné, il n’y a donc aucune clé à laquelle effectuer une substitution à l’intérieur. Ce que montre la trace à la place, c’est le même template workload: évalué une seconde fois, sur un contexte dont les données déclarées sensibles se lisent déjà comme <redacted>. Comme le template voit une chaîne là où il y avait une chaîne, le résultat conserve la forme du document émis : les mêmes champs, aux mêmes endroits, avec <redacted> à la position même de la donnée masquée et le texte littéral qui l’entoure inchangé.
Ce nouveau rendu diffère de ce qui a été émis de deux manières, toutes deux indiquées par la note :
- Un template qui se ramifie selon le contenu d’une valeur produit un rendu différent. Un
eqsur une valeur précise, un test de longueur, un hachage ou un encodage de celle-ci : chacun voit<redacted>et produit un résultat différent — une autre branche, une autre longueur, un autre digest. C’est pourquoi la trace ne prétend jamais montrer le document émis. - Les données qu’aucune déclaration ne nomme sont transmises sans changement. La substitution couvre ce que nomme l’axe — une feuille
values/infradéclarée, une clé de livraison marquée, une cléprovidesque le Component propre au composant déclare sensible, lesprovidesdéclarés d’une cible consommée, une feuille desvaluesouinfrapropres à une connexion que son socket déclare sensible, une feuille ou une cléprovidesdéclarée d’un rattachement que le composant détient lui-même (lu à.features.<name>) ou d’un rattachement écrit sur une connexion, et une valeurlocals:ousource:calculée à partir de l’un d’eux. Ce sont les mêmes données par lesquelles est masqué un refus levé par le template. Une donnée qui atteint le template par tout autre moyen, comme une cléprovidesqu’aucune déclaration ne nomme et dont une Recipe a calculé la valeur à partir d’une feuille déclarée, apparaît dans le nouveau rendu exactement comme elle apparaît dans le document émis.
Lorsque le nouveau rendu ne peut pas être produit du tout, l’emplacement conserve la clé workload: et remplace le document par une ligne qui le signale et nomme --trace-unredacted. Cette mention est délibérée : une projection qui aurait simplement disparu serait impossible à distinguer d’une Recipe qui ne déclare aucun workload:.
Une limite mérite d’être lue avant de considérer .trace/ comme sûr : dist/ n’est pas masqué. Les artefacts rendus sont émis exactement tels que le rendu les a produits, car ce sont eux qui sont déployés, et le nouveau rendu de la trace ne les atteint jamais — la même entrée produit un rendu identique à l’octet près, que --trace soit activée ou non.
Considérez .trace/ comme contenant du matériau sensible et traitez-le comme dist/ est traité.
Afficher les valeurs masquées
--trace-unredacted, avec --trace, écrit les valeurs déclarées sensibles dans les fichiers de trace au lieu du texte qui les remplace. Il existe parce que la valeur masquée est parfois celle que l’on débogue — un identifiant qui arrive depuis le mauvais attachement paraît identique au bon lorsque les deux apparaissent comme masqués.
C’est aussi le moyen de capturer le document que le build a réellement émis : rien n’étant masqué, il n’y a rien à substituer, si bien que les slots workload: contiennent le document émis plutôt qu’un nouveau rendu de celui-ci, et l’entrée workload_note est absente.
Trois propriétés le délimitent :
- Chaque fichier qu’il écrit indique ce qu’il est. Chaque fichier de trace produit par l’exécution commence par un commentaire qui nomme l’option et indique que les valeurs déclarées sensibles apparaissent en clair plus bas, de sorte qu’un fichier joint plus tard à un rapport de bug ou laissé dans un répertoire partagé porte son propre avertissement. Le commentaire est valide dans le format propre du fichier, si bien que le fichier reste analysable.
- Il atteint
.trace/et rien d’autre. Les artefacts rendus sont identiques octet pour octet avec ou sans lui — il change ce qu’affiche un fichier de débogage, jamais ce que produit un build — et les présentations deaggrega inspectainsi que le texte de diagnostic qu’affiche un build en échec sont identiques dans les deux états. - Il n’existe que dans l’invocation. Il n’existe aucun paramètre de configuration pour lui, de sorte qu’il ne peut pas être activé une fois et laissé actif pour tous ceux qui construisent le workspace par la suite. Le demander sans
--tracearrête le build avec un message qui nomme les deux options, plutôt que d’accepter une demande qu’il ne peut pas honorer.
Indépendamment de la trace, un build affiche un avis par clé de livraison qui transporte du contenu déclaré sensible sous forme de valeur littérale, en nommant le composant, la cible, l’attachement et la clé de livraison. Il n’arrête jamais le build et --no-unsupported-field-warnings ne le fait pas taire — cette option couvre ce qu’une cible ne peut pas honorer de ce que vous avez écrit, une autre classe.
Le mot-clé, ses deux emplacements d’écriture, la formulation exacte de l’avis et la limite complète de ce que sa déclaration permet d’obtenir se trouvent dans vocabulary/compact-form-authoring.md, « Déclarer une feuille sensible ».
Quand utiliser --trace
- Diagnostiquer pourquoi un manifeste rendu ne contient pas une valeur attendue : parcourez les dumps par passe pour trouver le premier slot où la valeur manque.
- Vérifier le déterminisme après une mise à niveau du compilateur : deux compilations de la même entrée avec
--traceproduisent des dumps de trace identiques octet pour octet ; toute différence par slot localise la régression. - Itération lors de l’écriture d’un catalogue : comparer les instantanés
04-inject-mapping.yamlet06-source-locals.yamlmontre ce que voient les templates de la Recipe au moment de l’évaluation.
Exemples
Compiler une Release avec le catalogue local :
aggrega build --release releases/production.yamlCompiler avec un répertoire de catalogue distinct :
aggrega build --release releases/production.yaml --catalog ../platform-catalog/Voir ce qu’une Release émettrait sans en écrire quoi que ce soit :
aggrega build --release releases/production.yaml --dry-runCompiler avec des dumps de trace pour le débogage :
aggrega build --release releases/production.yaml --traceAprès la compilation, inspectez .trace/boundaries/<boundary>/<instance>/ pour l’état de chaque passe. Le répertoire .trace/ est écrasé à chaque exécution avec --trace ; l’état de trace précédent n’est pas conservé d’une compilation à l’autre.
Références croisées
aggrega-pull— récupère des entités de catalogue depuis un registre OCI dans le catalogue local.aggrega-validate— vérifie la correction du catalogue, de la fermeture de la Release ou d’une seule entité sans émettre d’artefacts ; la validation des dépendances qu’exécute un build, sans le rendu.aggrega-lint— vérifie les conventions de publication du catalogue sur les trois mêmes portées.aggrega-inspect— interroge le graphe IR après la finalisation du graphe sans passer au rendu.- Erreurs — le format catégorisé de présentation des erreurs qui apparaît dans la CLI.
Synopsis
aggrega build [flags]Description
Compile an Aggregate and Release pair into provider-native artifacts under eachboundary's output directory.
The Release is the single entry point: it names the Aggregate and the Manifest,declares the boundaries, and routes each component to a provider. What aprovider emits is the provider's own shape — Helm manifests, a redistributableHelm chart, docker-compose YAML — so the output directory holds whatever theproviders this Release routes to produce.
The output directory is dist/ beneath the workspace root, whichever folder thecommand is run from, and the closing line names it in full. A run that finds noworkspace uses the folder it was run from as the root, and writes dist/ there.
Build is read-only by default and needs a lockfile. Run "aggrega pull" first tocreate one, or pass --auto-pull to fill it in-process for this build.
Given identical input, build writes byte-identical output, which is what makesthe rendered tree reviewable as a diff.Options
| Option | Par défaut | Description |
|---|---|---|
--auto-pull | false | Exécute l’étape de pull avant le build : résout les dépendances de la Release dans le lockfile et le cache au sein du processus, puis construit à partir d’elles. C’est le même remplissage au sein du processus qu’effectue le paramètre auto_pull du workspace, activé pour un seul build sans modifier la configuration du workspace. Seul, c’est un remplissage incrémental — les pins existants sont respectés, et les références sans pin sont résolues et ajoutées |
--catalog | [] | Répertoire de catalogue ; répétable. Chaque —catalog <dir> est ajouté en tête de la pile de recherche du catalogue (la première correspondance l’emporte) : les catalog_dirs du workspace ou, pour une Release à laquelle la configuration du workspace attribue ses propres répertoires sous workspace.releases, ceux de cette Release ; la pile se termine par le répertoire nommé catalog à la racine du workspace lorsqu’il existe. Une liste catalog_dirs écrite vide ne lit aucun catalogue local. |
--debug | false | Émet sur stderr des diagnostics détaillés lisibles par un humain — durée réelle par phase et nombre d’entités/de dépendances. Prime sur —quiet : la sortie détaillée est toujours émise. Distinct de —trace, qui écrit des fichiers intermédiaires par nœud lisibles par une machine dans .trace/ |
--detail | false | Le build est en lecture seule par défaut et n’affiche aucun détail de résolution. Lorsque l’étape de pull s’exécute — parce que —auto-pull a été passé ou que le workspace active auto_pull —, le build remplit le lockfile au sein du processus, qu’il en existe déjà un ou non, et cette option affiche pour chaque entité résolue ce que ce remplissage a fait : récupérée à neuf depuis un registre, réutilisation d’un slot du cache, trouvée dans un catalogue local, servie depuis l’intérieur du binaire du compilateur, ou externe (l’Aggregate ou le Manifest propre à la Release, lu depuis le fichier ou l’entrée que la Release nomme). Lorsqu’aucune étape de pull ne s’exécute, il affiche une ligne qui le signale au lieu des lignes par entité. Stdout uniquement ; non persisté |
--disable-plugin-cache | false | Ignore le cache persistant sur disque de compilation des plugins pour ce build et compile les guests de plugins à neuf dans un cache en mémoire qui est abandonné à la fin du build. Désactivé par défaut, ce qui réutilise le cache partagé sur disque d’un build à l’autre. Ne modifie pas la sortie rendue |
--dry-run | false | Effectue le rendu de la Release et affiche ce qu’elle émettrait au lieu de l’écrire : le chemin prévu de chaque artefact et son contenu vont sur stdout, et le répertoire de sortie et le lockfile restent intacts. Les entrées externes se comportent exactement comme dans un build ordinaire — les entrées épinglées sont servies depuis le magasin adressé par contenu (et réalimentées par digest lorsque le blob manque), et un rendu qui demande une URL externe non épinglée s’arrête en la nommant —, si bien que ce qu’affiche une exécution à blanc est ce qu’un build écrirait. Refuse d’être combiné avec —auto-pull, —upgrade ou —trace, qui écrivent chacun — exécutez le remplissage des dépendances, ou un build avec trace, comme une étape à part. Se combine avec —policy-input, dont les fichiers sont alors la seule chose qu’il écrit |
--ir-graph | false | Écrit également sur stdout, en JSON, le graphe IR calculé par cette exécution, en plus de tout ce que cette commande produit déjà. Les valeurs qu’un auteur a déclarées sensibles y sont masquées ; passez —unredacted pour les afficher à la place. Les artefacts sont toujours écrits et le résumé toujours affiché ; le graphe est écrit avant les deux |
--no-unsupported-field-warnings | false | Fait taire la classe d’avertissements sur les champs non pris en charge : les avis qu’une cible émet pour quelque chose que vous avez écrit et qu’elle ne peut pas honorer — un champ du Workload qu’elle ne peut pas exprimer (comme c’est le cas d’une cible de moindre fidélité telle que compose), ou une annotation aggrega.ai/ sur laquelle elle n’agit pas pour le type d’entrée du nœud. Les autres avertissements de rendu continuent d’apparaître. Affichage uniquement ; ne modifie pas la sortie rendue |
--policy-input | — | Écrit, dans ce répertoire, le payload que chaque rôle de gouvernance transmet à un plugin qui y est attaché, sous forme d’une ligne de JSON : exactement ce que le build transmet au plugin, chaque valeur que le build lui retient étant retenue ici aussi. Pour annotation-transform, label-transform et ir-verdict, le fichier est le document input que lit une politique à ce rôle. Pour render-verdict, le moteur de politiques remodèle le payload avant qu’une politique ne le lise — les documents de chaque artefact en sont analysés —, si bien qu’une politique render-verdict sur un moteur intégré se teste dans un build, attachée de sorte qu’elle rapporte au niveau warn ou info ; pour un plugin dont vous avez compilé vous-même le .wasm, aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json l’exécute sur ce fichier. Un rôle auquel rien n’est attaché est écrit aussi, comme le payload que recevrait un attachement sans sources ni réglages, de sorte qu’une politique peut être écrite avant d’être attachée. Chaque rôle est écrit dans <role>.json (annotation-transform, label-transform, ir-verdict, render-verdict) ; lorsque les attachements d’un même rôle reçoivent des payloads différents — l’un porte ses propres sources ou réglages, ou une transformation modifie ce que lit le suivant —, chacun est écrit à la place dans <role>.<position>.<plugin>.json, position comptant les attachements de ce rôle à partir de 1 dans l’ordre où la configuration du workspace les liste, et plugin étant le dernier segment de la référence du plugin sans sa version, chaque caractère qu’un nom de fichier ne peut pas contenir étant échappé. Les fichiers de ces noms déjà présents dans le répertoire sont remplacés, et rien d’autre n’y est touché. Les fichiers sont écrits que le build se termine ou s’arrête, et un build qui s’arrête avant qu’un rôle ne s’exécute nomme chaque rôle pour lequel il n’a écrit aucun fichier. Les demander ne modifie aucun artefact ni aucun verdict. Se combine avec —dry-run, qui écrit alors ces fichiers et rien d’autre : le répertoire de sortie et le lockfile restent intacts |
--progress | false | Force l’affichage de la progression du build même lorsque stderr n’est pas un terminal, en affichant une ligne simple par étape à mesure qu’elle se termine, avec sa durée. La valeur par défaut est auto : la checklist interactive des phases n’est affichée que lorsque stderr est un terminal qui interprète les séquences d’échappement, un terminal qui ne les interprète pas reçoit les mêmes lignes simples, et une sortie redirigée ou envoyée dans un pipe n’en reçoit aucune. —quiet et —debug priment tous deux sur —progress |
--quiet | false | Fait taire l’affichage de la progression du build sur stderr. N’affecte pas stdout. Prime sur —progress |
--release | — | Chemin du fichier YAML de la Release (obligatoire). Un chemin relatif est résolu par rapport au répertoire dans lequel vous exécutez la commande, et non par rapport à la racine du workspace. Lorsque ce répertoire n’appartient à aucun workspace et qu’aucune racine n’est indiquée, un chemin absolu trouve le workspace à partir du dossier propre de la Release |
--trace | false | écrit des fichiers intermédiaires par nœud dans .trace/ sous la racine du workspace, à côté de dist/, pour une inspection post-mortem |
--trace-unredacted | false | Écrit les valeurs déclarées sensibles dans les fichiers .trace/ au lieu du texte |
--unredacted | false | Affiche les valeurs qu’un auteur a déclarées sensibles au lieu de les masquer. Tout ce que la sortie atteint — un terminal, un pipe, un fichier, un enregistrement d’écran — contient alors ces valeurs en clair. Atteint le graphe qu’écrit —ir-graph et rien d’autre, il nécessite donc —ir-graph ; les fichiers .trace/ utilisent —trace-unredacted à la place |
--upgrade | false | Fait de l’étape d’auto-pull une actualisation complète : abandonne le lockfile existant et résout à nouveau chaque dépendance à partir de l’état actuel du registre, en portant chacune à la version la plus élevée disponible au lieu de respecter les pins existants. Implique —auto-pull — seul, il exécute un pull d’actualisation complète avant le build. Il n’accepte pas de cible, il ne peut donc pas être restreint à une seule dépendance : pour adopter ou abandonner un seul pin, exécutez plutôt aggrega pull —upgrade —release |
--verify-determinism | false | Effectue le rendu de chaque nœud deux fois et compare les octets émis, en arrêtant le build si les deux rendus d’un nœud diffèrent. Désactivé par défaut. Utilisez-le pour confirmer qu’un provider effectue un rendu déterministe — une entrée identique produit une sortie identique octet pour octet —, ce sur quoi reposent les garanties de diff GitOps et de sortie identique octet pour octet |
--yes | false | Répond à l’avance à la confirmation de —upgrade, pour un usage non interactif. Il atteint cette seule invite et rien d’autre : un build qui n’actualise pas ne demande rien, donc le passer n’y change aucun comportement |