aggrega inspect
aggrega inspect produit une vue lisible de n’importe quelle entité Aggrega — un Component de catalogue, un fichier d’entité rédigé, une entité publiée dans un registre ou une Release entièrement résolue. C’est l’interface de débogage canonique pour comprendre ce que le compilateur va produire : quels Components étendent quelles bases, quelle Recipe correspond à chaque type, quelles Features se rattachent à chaque nœud, et d’où viennent exactement les contributions de chaque Feature.
Chaque type d’entité a une vue naturelle de «contrat ». inspect montre ce contrat — le schéma qu’un Component publie, les mappings qu’un Manifest déclare, la topologie qu’un Aggregate construit, les rattachements de Feature par nœud vers lesquels une Release se résout. Les tutoriels et les contenus conceptuels se trouvent ailleurs ; inspect répond à la question «vers quoi cette entité se résout-elle réellement ? »
Un seul argument positionnel est aiguillé selon la forme de son contenu ; aucune sous-commande n’est nécessaire. La commande aiguille selon l’heuristique suivante :
| Forme de l’identifiant | Aiguillage | Sortie |
|---|---|---|
Commence par ./, ../ ou /, ou se termine par .yaml / .yml | Branche fichier | Inspection par fichier, selon l’en-tête kind: du fichier. |
Commence par oci:// | Branche registre | L’entité publiée à cette coordonnée, lue depuis son registre et rendue par la vue que reçoit un fichier de son type. Voir Lire une entité publiée. |
| Tout le reste | Branche catalogue | Rechercher l’identifiant dans la pile de recherche du catalogue pour tous les types d’entités ; résoudre les chaînes extends: ; rendre la vue propre au type trouvé. |
Trois niveaux de détail
--list, le niveau par défaut et --detail forment une discipline uniforme de verbosité à trois niveaux que chaque type respecte. --list et --detail s’excluent mutuellement — passer les deux est refusé plutôt que résolu silencieusement.
--list— identifiants uniquement. Un Component liste son nom et les noms de ses sockets uses ; une MappingLibrary liste les noms de ses mappings ; un Aggregate liste les noms de ses composants avec leurs types.- par défaut — une vue d’ensemble structurée adaptée à un usage interactif. Elle s’ouvre sur l’identité de l’entité et, pour chaque type sauf un Manifest et une Release, sur sa description lorsque l’entité en rédige une ; une entité sans description n’en affiche aucune plutôt qu’une ligne vide. Le reste de la forme dépend du type : un Component montre son schéma et ses sockets ; un Aggregate montre les composants, leurs valeurs et leurs arêtes avec les rattachements que porte chaque connexion, ainsi que le graphe des dépendances ; une Release montre l’arbre des nœuds par boundary avec les rattachements de Feature, chacun de ceux écrits sur une connexion étant listé sous cette connexion.
--detail— corps complets des champs. Tout ce que porte le type : un Component ajoute ses mécanismes d’auto-injection, les Features requises et les labels ; une MappingLibrary développe le corps complet du template de chaque mapping ; une Recipe ajoute le corps de son workload, ses provides et ses assertions.
Quelques types utilisent les niveaux pour faire apparaître progressivement une plus grande partie d’un corps rédigé. Une MappingLibrary avec --list montre les noms des mappings ; au niveau par défaut, elle ajoute l’exemple d’utilisation synthétisé de chaque mapping ; avec --detail, elle développe le corps complet du template.
Résolution : --raw et --resolved
Chaque type a une profondeur de résolution par défaut naturelle (voir le tableau ci-dessous). --raw et --resolved sont des surcharges toujours disponibles, et ils s’excluent mutuellement — passer les deux est refusé plutôt que résolu silencieusement :
--rawdésactive toute résolution — l’entité est émise telle que rédigée, directement depuis le fichier.--resolvedactive la profondeur de résolution complète du type.
Pour les types affichés par défaut tels que rédigés, --raw est sans effet et --resolved déclenche la résolution que le type prend en charge. Pour les types résolus par défaut, --raw est le contournement vers la forme rédigée.
--raw reproduit le fichier, donc une valeur qu’un auteur a déclarée sensible y apparaît exactement telle que rédigée. C’est le contrat, pas une lacune — une vue telle que rédigée qui masquerait discrètement une partie d’elle-même ne serait pas telle que rédigée. Traitez la sortie de --raw comme vous traitez le fichier d’entité dont elle provient. --output yaml reproduit le fichier de la même façon, pour chaque type, Release comprise.
Une Release répond à deux questions supplémentaires, et chacune est un document différent avec son propre flag. Le graphe compilé vers lequel se résout une Release est --ir-graph ; sa clôture de dépendances est --closure. Voir Sortie lisible par une machine et La clôture de dépendances : --closure ci-dessous.
Valeurs par défaut par type
inspect connaît les types inspectables de manière autonome du tableau ci-dessous. Les types de catalogue sont rendus par défaut tels que rédigés — leurs fichiers sont des contrats autonomes. Les types d’instance utilisent par défaut une vue résolue, car leur YAML rédigé n’est que le point de départ d’une cascade ou d’un pipeline.
| Type | Par défaut | Ce que signifie «résolu » |
|---|---|---|
| Component | tel que rédigé | Le fichier est un contrat autonome ; la résolution se fait par rapport à une liaison du Manifest, exposée via --show-implements. |
| Feature | tel que rédigé | Comme pour Component. |
| Recipe | tel que rédigé | --show-implements résout la référence au Component dans spec.implements. |
| FeatureRecipe | tel que rédigé | --show-implements résout la référence à la Feature dans spec.implements. |
| MappingLibrary | tel que rédigé | Les entrées sont des chaînes de template Go opaques ; le rendu a lieu au moment de la consommation. |
| SchemaLibrary | tel que rédigé | Les entrées sont des définitions de schémas et de templates réutilisables, résolues au moment de la consommation. |
| WorkloadLibrary | tel que rédigé | Les entrées sont des corps de Workload réutilisables qu’une Recipe importe, évalués au moment de la consommation. |
| ArtifactLibrary | tel que rédigé | Les entrées sont des bundles d’artefacts réutilisables qu’une Recipe importe, rendus au moment de la consommation. |
| Plugin | tel que rédigé | Le fichier est un contrat de plugin autonome : types de sockets, capacités par export, contraintes d’exécution et pointeur de signature. Adressable par son chemin de fichier, ou par sa coordonnée <pluginType>/<name> dans le catalogue. |
| Manifest | résolu | La chaîne extends: est appliquée ; les mappings de composants et de features résolus sont présentés. |
| Aggregate | résolu | La topologie est construite — le graphe uses et l’ordonnancement sont calculés. |
| Release | résolu | Le pipeline complet s’exécute : résolution, expansion des annotations, exécution des gardes, construction de la topologie, construction de l’IR. |
Un fichier dont le kind: est Workload est rejeté : un Workload n’existe qu’intégré dans une Recipe et n’est pas une entité inspectable de manière autonome. Inspectez une Recipe pour voir son Workload.
Profondeur de résolution par type
La plupart des types n’ont pas de pipeline — inspect lit le fichier et le rend. Trois types d’instance font l’objet d’une véritable résolution :
- Manifest applique sa chaîne
extends:— en suivant les imports de fichiers — et rend les mappings de composants et de features fusionnés.--rawmontre le fichier tel que rédigé. - Aggregate construit sa topologie : le graphe uses est construit et l’ordre des dépendances est calculé. La vue par défaut montre les composants avec leurs valeurs et leurs arêtes, suivis du graphe des dépendances.
--rawmontre l’arbre des sous-systèmes tel que rédigé. - Release exécute l’intégralité du pipeline de compilation jusqu’à l’IR — résolution, expansion des annotations, exécution des gardes, construction de la topologie, construction de l’IR — et rend l’arbre des nœuds par boundary avec les rattachements de Feature de chaque nœud et leur provenance. Les rattachements de gouvernance qui façonnent le graphe s’exécutent dans ce pipeline au lieu d’être ignorés pour une vue, de sorte que ce que vous lisez reflète ce qu’ils ont décidé : les labels d’un rattachement
label-transformsont en place avant que quoi que ce soit ne soit comparé à eux, et les annotations injectées par un rattachementannotation-transformse développent en rattachements de Feature exactement comme une annotation que vous avez rédigée. Un rattachement dont cette commande ne peut pas résoudre le plugin l’arrête, plutôt que de vous laisser un graphe dessiné sans les décisions de ce plugin. Une Release qui en étend une autre est dessinée, dans cette vue et dans--ir-graph, comme la Release que compose sa chaîneextends:— celle que lit un build de cette Release —, de sorte qu’une Release qui ne nomme que sa Release parente montre l’Aggregate, le Manifest et les boundaries de cette parente sous son propre nom. Le Manifest que nomme une Release est lui aussi composé à travers sa propre chaîneextends:, que la Release étende quelque chose ou non, de sorte qu’un rattachement dont ce Manifest hérite le mappage montre la réalisation qu’utilise un build.--rawémet le fichier de la Release tel quel, sans pipeline.--closurepose une question différente sur la même Release et n’exécute aucun pipeline ; voir La clôture de dépendances :--closure.
Il n’existe pas de flag de profondeur distinct ; la bascule --raw / --resolved est le seul contrôle de la résolution, superposé à la valeur par défaut naturelle de chaque type.
Comportement en cas d’erreur
Un fichier voisin référencé qui ne se charge pas arrête immédiatement la commande — une Release pointant vers un Aggregate manquant, une entité de catalogue défectueuse dans la pile de recherche. Elle s’arrête avec un message clair au lieu de rendre une sortie partielle, et il n’existe pas de mode continue-on-error pour un échec de chargement : dès qu’un document dont la résolution a besoin est illisible, il n’y a plus rien à résoudre. Lorsque la résolution d’un nom s’arrête sur un document de catalogue que le chargement refuse, le message indique ce refus une seule fois : un en-tête portant la catégorie et, lorsque le refus nomme une condition, son code court, puis le document, puis ce qui ne va pas — pour un document que le schéma de son type refuse, la ligne et la contrainte qu’il enfreint. Il ne suggère pas de déplacer le fichier — le catalogue l’a lu, et c’est pourquoi il a été refusé.
Une Release dont les contrôles du compilateur rejettent la composition est refusée plutôt que rendue. Résoudre une Release construit le graphe, et les contrôles qu’un build effectue sur le graphe terminé — une arête uses: dont la cible ne satisfait pas le selector: de son socket, une Feature rattachée à un composant que son appliesTo: n’admet pas, et les autres — sont aussi effectués ici, avec le diagnostic qu’affiche un build des mêmes documents. Le refus nomme chaque constat en une seule exécution au lieu de s’arrêter au premier, de sorte qu’une seule passe vous montre toute la liste à corriger plutôt que sa première entrée. C’est ce qui garde cette commande honnête vis-à-vis d’un déploiement : une vue qui rendrait une composition que le build refuse présenterait comme correct un workspace qui ne l’est pas. Les sélections qui ne résolvent rien ne sont pas concernées — --raw, --output yaml et --closure reproduisent ou résolvent ce que vous avez rédigé sans construire de graphe.
Une Release dont le lockfile ne correspond plus à ce vers quoi elle se résout est refusée avec l’arrêt qu’affiche aggrega build. Lorsqu’un lockfile se trouve à côté de la Release, chaque sélection qui résout la Release — la vue par défaut, --resolved, --ir-graph et --closure — le confronte à ce vers quoi la Release se résout, avec la comparaison de dérive qu’un build effectue avant de rendre. Un lockfile qui ne correspond plus arrête la commande avec le refus E0130 du build : chaque entrée qui a dérivé, puis la commande aggrega pull --release <release> qui la corrige. Rien n’est écrit sur la sortie standard et la commande se termine avec un code non nul, car une image tirée du catalogue dans son état actuel montrerait ce qu’aucun build de cette Release ne rend. --raw et --output yaml seuls ne lisent ni le lockfile ni le catalogue, et n’y sont pas soumis. Une Release sans lockfile à côté est résolue sur le catalogue dans son état actuel.
Un fichier dont le kind: n’est pas reconnu signale le type inconnu et le fichier dont il provient. Un fichier Workload signale que le type est uniquement intégrable et nomme l’entité dans laquelle il s’intègre. Un identifiant oci:// qui ne peut pas être lu est refusé avec la condition qui en nomme la raison ; Lire une entité publiée les liste.
Résolution du catalogue
La pile de recherche du catalogue est assemblée selon une priorité en couches : les flags --catalog (ajoutés en tête, dans l’ordre) viennent d’abord, puis les catalog_dirs du workspace issus de .aggrega-config.yaml — pour une Release à laquelle la configuration attribue ses propres répertoires sous workspace.releases, ceux de cette Release à leur place — puis le répertoire catalog à la racine du workspace, qui est lu que quelque chose le nomme ou non. Un workspace dont le catalog_dirs est écrit sous forme de liste vide ne lit aucun catalogue local. La pile est first-win — le premier répertoire à déclarer une identité d’entité en est propriétaire ; la copie d’un répertoire ultérieur est masquée. La branche catalogue résout l’identifiant par rapport à cette pile pour tous les types d’entités, selon une priorité fixe, et rend la première correspondance via la vue propre à ce type ; les branches fichier et release y chargent les entités de catalogue référencées lorsqu’un mapping du Manifest ou un parent extends: doit être résolu. Un parent extends: que la pile ne contient pas est lu là où un build le lit : depuis le cache d’artefacts, sous le pin que le lockfile d’une Release enregistre pour lui — celui de la Release nommée, ou celui de chaque Release que contient le workspace lorsqu’aucune n’est nommée. Une base publiée dans un registre se résout donc ici une fois que aggrega pull l’a récupérée et épinglée, et avant cela la commande est refusée en nommant aggrega pull --release <release>. Rien n’est récupéré.
Rechercher un nom dans les termes d’une Release
Un nom donné seul est recherché dans la pile propre au workspace. Ajoutez --release <release-path> à côté et le nom est recherché à la place dans la pile de cette Release — les répertoires que la configuration du workspace attribue à cette Release, précédés des éventuels --catalog — ce qui correspond à ce que lit un build de cette Release. Un workspace qui conserve une variante de catalogue par Release, chacune déclarant la même entité, répond donc à un nom avec la variante avec laquelle cette Release est construite :
aggrega inspect core/datastore/mariadb --release release-helm-synth.yamlUn nom que la pile de cette Release ne résout pas est refusé, et l’indication de l’endroit où sont lues les entités locales nomme l’entrée de cette Release sous workspace.releases, puisque c’est cette entrée que la recherche a lue. --release choisit la pile dans laquelle un nom est recherché, il ne s’applique donc qu’à un nom seul : un chemin de fichier et une référence de registre sont lus tels quels et le refusent. Un --release nommant un fichier inexistant, ou nommant un répertoire, est refusé avant toute recherche.
Lire une entité publiée
aggrega inspect oci://<host>/<repository>:<tag> lit l’entité publiée à cette coordonnée ; @<digest> à la place de :<tag> nomme exactement un manifest. C’est ainsi que vous examinez une entité qui n’existe que dans un registre — le dépôt est le segment du type suivi de l’identité de l’entité, comme l’expose le §6 de Catalogue et registre, et aggrega push affiche la référence à laquelle il a publié, qui se lit ici précédée de oci://.
Ce que vous voyez est l’entité telle qu’elle a été publiée. Une entité publiée avec les fichiers qu’elle déclare — une Recipe avec son chart local ou son lock, un Component avec un schéma qu’il importe — est livrée sous forme d’archive, et l’entité en est extraite : le document à la racine de l’archive qui déclare un type publiable, de sorte qu’un template de chart ou un fragment compose livré à côté n’est pas confondu avec elle. Une entité qui ne déclare aucun fichier est livrée sous la forme de son document inchangé, et l’entité d’un Plugin est lue depuis son manifest plutôt que depuis l’exécutable publié avec lui. Le document est ensuite rendu par la même vue que reçoit un fichier de ce type, avec les mêmes niveaux de détail et les mêmes --raw et --output yaml. Aucun héritage n’est appliqué : la vue porte sur ce que l’éditeur a placé à cette coordonnée. Les présentations lisibles se terminent par ce qui a été lu : la coordonnée, si elle contenait l’entité sous forme d’archive ou de document lui-même, le type de média que déclare son manifest et le digest de ce manifest, qui relit les mêmes octets lorsqu’il est écrit sous la forme @<digest> à la place de :<tag> ; --output yaml affiche le document et rien après.
Ce qu’elle vérifie, et ce qu’elle ne vérifie pas. Les octets récupérés sont vérifiés par rapport au digest que le manifest propre de l’artefact enregistre pour eux, ce qui établit qu’il s’agit des octets que nomme ce manifest. C’est une vérification par rapport à ce que le registre a servi plutôt que par rapport à quoi que ce soit enregistré au préalable : aucune signature attachée à l’artefact n’est vérifiée, et aucun retrait enregistré à son encontre n’est signalé. Rien n’est écrit — ni entrée de cache ni lockfile — de sorte que lire une coordonnée ne change rien à ce qu’un build ultérieur résout.
Elle accède au réseau. Le registre est contacté avec les identifiants que cette machine détient pour lui, depuis le même magasin que lisent aggrega push et aggrega pull, et un registre sur cette machine est contacté en HTTP simple. Un workspace hors ligne refuse la lecture avant toute connexion.
Une lecture qui ne peut pas répondre se termine avec un code non nul et n’affiche rien sur la sortie standard. Chaque échec ci-dessous nomme sa condition ainsi que la marche à suivre ; un registre qui ne peut pas du tout être atteint est signalé avec l’erreur réseau qui a interrompu la lecture :
| Ce qui s’est passé | Condition |
|---|---|
| Rien n’est publié sous la référence | E0137 |
| Le registre a refusé l’identifiant, ou aucun n’est stocké pour lui | E0138 |
| Le workspace est hors ligne | E0125 |
| L’artefact est une archive qui ne peut pas être extraite | E0300 |
| L’archive ne contient aucun document d’entité à sa racine | E0298 |
| L’archive contient plus d’un document d’entité à sa racine | E0299 |
| Le document n’est pas une entité d’un type que publie un registre | E0301 |
Chaque code est listé dans la référence des erreurs. Une référence qui ne nomme aucun dépôt, ou ni tag ni digest, est refusée avec la forme à écrire à la place. --ir-graph et --closure sont refusés avant toute récupération, car aucun type que publie un registre n’est une Release.
Avis de dépréciation et de retrait
Un éditeur peut enregistrer un marqueur sur un artefact après l’avoir publié, indiquant que la version publiée est dépréciée ou retirée. Lorsque la branche catalogue résout une entité, inspect signale un tel marqueur sous la vue propre de l’entité — pour chaque type qu’elle résout par nom, et pas seulement pour un Component.
L’avis nomme la sévérité que l’éditeur a enregistrée — warning, error ou retracted — ainsi que la version sur laquelle le marqueur a été enregistré, la raison, le remplacement lorsqu’il en est nommé un, et la date d’émission. Les trois sévérités sont signalées. C’est un ensemble plus large que celui qui change ce vers quoi un build se résout : une version marquée retracted est exclue de la sélection des versions, tandis que warning et error sont consultatives et toujours sélectionnées. inspect vous montre ce qu’un éditeur a déclaré ; il ne décide pas de ce que vous obtenez.
L’avis est lu depuis l’index local du registre à partir duquel l’entité se résout, que construit aggrega registry update — il ne nécessite donc pas de réseau et fonctionne dans un workspace hors ligne. Comme l’index est un instantané, l’avis se termine en indiquant quand cet instantané a été pris et nomme la commande qui le rafraîchit. Un workspace sans index construit ne signale rien, et un avis absent signifie donc «rien d’enregistré dans cet instantané » plutôt que «rien d’enregistré ».
Un marqueur n’est signalé que lorsque sa propre signature est vérifiée par rapport aux signataires que reconnaît la politique de confiance du registre. Un marqueur non signé, ou dont la signature n’est pas vérifiée, n’est pas signalé : une affirmation qui ne peut pas être authentifiée n’est pas présentée comme un fait.
L’avis accompagne les vues lisibles par un humain. Ni --output yaml ni --ir-graph n’en ajoute un, de sorte qu’un consommateur qui analyse l’une ou l’autre reçoit un document et rien d’autre.
Exemples détaillés
Recherche d’un Component dans le catalogue
$ aggrega inspect core/server:1.0.0 --catalog ./catalog
Component: core/server:1.0.0Schema: | values: { port?: int | *8080 }Uses sockets: db: selector="component.aggrega.ai/type=stateful-server"La vue par défaut affiche la description du Component s’il en rédige une, puis le schéma résolu (après une éventuelle fusion extends:) et les uses-sockets déclarés. Le Component ci-dessus ne rédige aucune description, c’est pourquoi la transcription s’ouvre directement sur le schéma. --detail ajoute les mécanismes de self-inject, les Features requises et les labels ; --list affiche uniquement l’identifiant du Component et les noms de ses sockets.
Feature
$ aggrega inspect ./features/metrics.yaml
Feature: core/metrics:1.0.0Schema: | values: { port?: int | *9090 }Uses sockets: backend: selector="component.aggrega.ai/type=stateful-server" inject: [env]Secret slots: token (required)Targeting: appliesTo: component.aggrega.ai/type=serverLabels: feature.aggrega.ai/category: observabilityRecipe avec --show-implements
La vue par défaut d’une Recipe affiche une section par mode d’entrée qu’elle déclare, sa capacité et son mappage de valeurs. --show-implements résout la référence spec.implements par rapport au catalogue et affiche le Component lié, ainsi que les rattachements que ce Component requiert :
$ aggrega inspect ./recipes/api-server-recipe.yaml --show-implements --catalog ./catalog
Recipe: core/api-server-recipe:1.0.0Implements: core/api-server:1.0.0Capability: helm## Synthesized workload: inlinevaluesMapping: (none)Implements Component: core/api-server:1.0.0 requires attachment (observability): core/metricsRecipe déclarant plusieurs modes d’entrée
Les modes d’entrée d’une Recipe se composent par addition : un source: à rendre, un workload: à synthétiser et une map artifacts: contribuent chacun à la sortie, et une Recipe peut en déclarer n’importe quelle combinaison. inspect signale chaque mode que la Recipe déclare au lieu d’en choisir un, de sorte que ce que vous voyez est l’ensemble que vous avez rédigé :
$ aggrega inspect ./recipes/api-server-composed.yaml
Recipe: core/api-server-composed:1.0.0Implements: core/api-server:1.0.0Capability: helm## Sourced source: oci://charts.example.com/api-server:2.1.0## Synthesized workload: inlinevaluesMapping: inline templateArtifacts: 2 - servicemonitor.yaml - networkpolicy.yamlLes sections sont ordonnées source: → workload: → artifacts:, le même ordre qu’applique un build lorsqu’il résout une Recipe en un seul nom de mode et lorsqu’il signale quel mode déclaré le provider lié ne peut pas honorer — ainsi cette vue et les diagnostics d’un build nomment les modes dans le même ordre. Une Recipe ne déclarant ni source: ni workload: est signalée comme artifacts uniquement, ce qui est le seul cas où la vue nomme un mode unique.
Manifest (résolu par défaut)
$ aggrega inspect ./prod-manifest.yaml
Manifest: prod-manifest:1.0.0
Component Mappings: Type → Recipe core/compute/api-server helm-api-server-synthesized-with-artifacts:1.0.0 core/compute/web-ui helm-web-ui-synthesized-with-artifacts:1.0.0 core/datastore/postgres helm-postgres-synthesized-with-artifacts:1.0.0
Feature Mappings: Type → FeatureRecipe core/k8s-dns-resolver k8s-dns-patcher:1.0.0
Annotation Bindings: (none)La vue par défaut applique la chaîne extends: du Manifest et présente les mappages résolus des composants et des fonctionnalités ainsi que les liaisons d’annotations. --raw affiche le fichier tel qu’il a été rédigé, avant la résolution d’extends.
Aggregate (résolu par défaut)
$ aggrega inspect ./fullstack-app.yaml
Aggregate: fullstack-app:1.0.0
Components: backend (type: core/compute/api-server) Values: (none) Uses: databases: - data.main-db frontend (type: core/compute/web-ui) Values: (none) Uses: apis: - my-api → backend main-db (type: core/datastore/postgres) Values: database_name: app_production Uses: (none)
Dependency Graph: data.main-db ↑ backend backend ↑ frontendLa vue par défaut construit la topologie et affiche chaque composant avec ses valeurs et ses arêtes uses, suivis du graphe de dépendances calculé. L’arborescence des sous-systèmes est rendue avec imbrication ; --flat rend une section par nœud, chacune identifiée par son chemin pointé complet.
Une connexion écrite sous la forme longue est suivie des rattachements qu’elle porte, chacun sous le nom qu’il prend sur le composant consommateur — l’alias de la connexion et le slot joints par un point —, avec le type de Feature qu’il nomme et une clause indiquant le slot qu’il remplit et s’il manipule du matériel déclaré sensible :
gateway (type: conn/gateway) Values: region: eu Uses: models: - gpt → model - gpt.credential (feature.conn/token) [slot: credential, sensitive]Le slot et la marque sont les faits qu’un build d’une Release déployant cet Aggregate enregistre pour le rattachement, lus de la même manière que dans la vue de la Release (voir Connexion, slot et clause de sensibilité d’un rattachement) ; ils proviennent de la déclaration de slot du socket et de celle de la Feature elle-même, et ne dépendent donc pas de la Release qui déploie l’Aggregate. Un Aggregate ne nomme aucun Manifest, de sorte que la réalisation que le Manifest d’une Release choisit pour le rattachement n’est pas affichée ici. Cette vue liste les connexions d’un composant et ce qu’elles portent ; les rattachements du bloc propre d’un composant apparaissent dans la vue de la Release.
Release (résolue par défaut)
La vue de la Release est l’inspection aux enjeux les plus élevés. Elle exécute le pipeline complet et rend, par frontière, chaque nœud Component, ses arêtes uses et chaque Feature rattachée à ce nœud — celle écrite sur une connexion sous l’arête de cette connexion —, chacune avec le slot de rattachement qu’elle remplit, si elle manipule du matériel déclaré sensible et la FeatureRecipe qui la réalise, plus un crochet de provenance révélant d’où provient le rattachement :
$ aggrega inspect ./prod-release.yaml --catalog ./catalog
Release: prod-release:1.0.0
Boundary: backend-ns Directory: ./dist/backend Annotations (provider-consumed): aggrega.ai/namespace: backend-zone Component: backend (type: core/compute/api-server:1.0.0) Uses: data.main-db → data.main-db [cross-boundary] Features: (none)
Boundary: frontend-ns Directory: ./dist/frontend Annotations (provider-consumed): aggrega.ai/namespace: frontend-zone Component: frontend (type: core/compute/web-ui:1.0.0) Uses: my-api → backend [cross-boundary] Features: - cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]
Boundary: data-ns Directory: ./dist/data Annotations (provider-consumed): aggrega.ai/namespace: database-zone Component: data.main-db (type: core/datastore/postgres:1.0.0) Features: (none)Chaque frontière porte son répertoire de sortie et ses annotations consommées par le provider ; chaque composant sous une frontière porte son type de composant dans l’Aggregate, ses arêtes uses (les arêtes inter-frontières étant marquées), chacune suivie des rattachements que porte cette connexion, et ses propres rattachements de Feature, chaque rattachement avec sa clause de faits et son crochet de provenance. --flat réduit l’arborescence des frontières à une section par frontière identifiée par son chemin complet. --raw émet le fichier de la Release tel quel, sans pipeline.
Sortie YAML
$ aggrega inspect core/server:1.0.0 --output yaml --catalog ./catalog
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/server version: 1.0.0 labels: component.aggrega.ai/type: serverspec: usesSchema: db: selector: component.aggrega.ai/type=stateful-server schema: values: port: {type: integer, default: 8080}Un Component nommé depuis le catalogue est affiché comme l’entité que le catalogue a résolue, de sorte qu’après une fusion extends: vous voyez l’entité fusionnée plutôt que le fichier rédigé ; un fichier de Component est affiché tel qu’il a été rédigé.
Sortie lisible par machine
Deux flags produisent une sortie lisible par machine, et ils répondent à des questions différentes. --output choisit un format pour le document que cette commande rend déjà ; --ir-graph demande un document différent — le graphe compilé en lequel se résout une Release — en plus de celui-ci. Ils sont indépendants : en passant les deux, vous obtenez le graphe et le YAML tel que rédigé, chacun une fois.
--output yaml émet l’entité telle qu’elle a été rédigée, adaptée aux pipes et aux diffs. Cette sortie est verbatim, y compris les valeurs qu’un auteur a déclarées sensibles — une sortie prétendant reproduire l’entrée ne peut pas en masquer une partie tout en continuant à la reproduire. Transmettez-la, stockez-la et partagez-la comme vous le feriez du fichier d’entité dont elle provient.
Le graphe compilé : --ir-graph
aggrega inspect <release> --ir-graph écrit sur la sortie standard, en JSON, le graphe en lequel l’exécution s’est résolue, avant la vue que la commande rend de toute façon. Un seul document JSON, un seul saut de ligne final, de sorte qu’un consommateur qui décode le flux lit le graphe et s’arrête.
Il s’applique à une Release, qui est le seul type qui se résout en un graphe. S’il est demandé pour tout autre type, ou pour une entité du catalogue par son nom, la commande refuse et le dit, au lieu de rendre la vue propre à cette entité et d’abandonner silencieusement la demande.
Une composition que les vérifications du compilateur rejettent ne produit aucun graphe. Le refus décrit dans Comportement en cas d’erreur a lieu avant que quoi que ce soit ne soit écrit dans ce flux, de sorte qu’un pipeline qui le lit ne reçoit jamais un graphe qu’un build des mêmes documents refuserait — il reçoit les mêmes constats qu’un build signalerait, et un code de sortie non nul.
Le même flag, avec le même sens, existe sur aggrega build et aggrega validate : chacun renvoie le graphe que cette exécution a calculé, en plus de tout ce que cette commande produit par ailleurs. Une intégration d’éditeur lit le même graphe via le protocole du daemon.
--output yaml n’émet pas le graphe. Il reproduit la Release telle que rédigée, exactement comme pour tout autre type. Un pipeline qui veut le graphe le lit plutôt depuis --ir-graph, et reçoit du JSON plutôt que du YAML.
Le graphe masque. Ce n’est pas un fichier que quelqu’un a écrit — c’est ce que la compilation a calculé à partir de l’Aggregate, de la Release et du catalogue —, il n’y a donc aucun engagement de fidélité à la forme rédigée à respecter, et les mêmes déclarations qui régissent les présentations lisibles le régissent. Partout où le graphe porte une feuille qu’un auteur a déclarée sensible, la valeur est remplacée par un objet à clé unique qui l’indique comme masquée :
"values": { "secretName": "db-creds", "vault": { "token": { "aggrega_withheld": "declared" } }}La clé subsiste, de sorte que le graphe indique toujours quelles feuilles portent un nœud et ses rattachements ; seule la valeur disparaît. Un élément frère non déclaré dans la même charge utile est émis tel que rédigé — secretName ci-dessus est un localisateur public que son auteur a laissé non déclaré, et il s’affiche. La raison qui accompagne le marqueur indique pourquoi la valeur est absente : declared pour une feuille couverte par une déclaration, et unreadable lorsque la charge utile est arrivée sous une forme que cette commande n’a pas pu lire, auquel cas toute la charge utile est masquée plutôt que d’en deviner une partie.
La configuration propre d’une connexion est masquée de la même manière. Les values par connexion qu’un Aggregate écrit sur une entrée uses et l’infra par connexion qu’une Release y écrit sont régis par le socket du composant consommateur — le valueSchema et l’infraSchema qu’il déclare, les contrats par rapport auxquels cette configuration est validée — et jamais par les déclarations de la cible. Une feuille que l’un ou l’autre contrat déclare sensitive: true est remplacée par le marqueur dans les values et l’infra de l’arête, ainsi que dans l’entrée uses du nœud consommateur, qui porte les valeurs telles que l’auteur les a écrites ; chaque arête liste les feuilles qu’elle masque sous sensitive_payload_leaves, le champ qu’un nœud utilise pour les siennes. Une feuille du même nom sur une connexion dont le socket la déclare lisible est émise telle qu’elle est écrite.
Passez --unredacted lorsqu’un pipeline a réellement besoin des valeurs, et traitez ce qu’il produit comme vous traitez les fichiers d’entité eux-mêmes. aggrega build et aggrega validate acceptent le même flag à côté de --ir-graph, aux mêmes conditions : le graphe qu’ils renvoient masque les valeurs à moins qu’il ne soit passé.
Le protocole du daemon fournit le même graphe selon la même règle. aggrega/irGraph répond avec ces valeurs masquées, et ne les renvoie en clair qu’à une requête qui définit son champ unredacted — la forme que prend ce flag dans le protocole. Ainsi, ce qu’un panneau d’éditeur dessine suit les mêmes déclarations, et un client qui affiche les valeurs le fait parce qu’il les a demandées.
La fermeture des dépendances : --closure
aggrega inspect <release> --closure signale la fermeture des dépendances de la Release : chaque entité du catalogue qu’elle atteint, à la version en laquelle chacune s’est résolue, ainsi que les identités de l’Aggregate et du Manifest en lesquelles ses deux pointeurs se sont résolus et les documents partagés sur lesquels s’appuient ces entités. Rien n’est rendu et aucun artefact n’est produit — la fermeture est résolue, pas construite, de sorte qu’aucun provider n’est chargé pour y répondre.
La fermeture et la vue résolue sont des documents différents, et aucun ne peut être reconstitué à partir de l’autre. La vue résolue — ce que cette commande rend par défaut pour une Release — dit à quoi ressemble le déploiement : ses frontières, ses nœuds de composants, ce qui est relié à quoi et ce qui est rattaché à chaque nœud. La fermeture dit ce qui a été intégré pour le construire, et à quelles versions. Une entité peut être atteinte sans jamais apparaître comme nœud — la Recipe vers laquelle un Manifest mappe un type de composant est atteinte par chaque build et n’est un nœud dans aucun d’eux —, et un nœud enregistre le type de composant sous lequel il a été déclaré, pas la version en laquelle ce type s’est résolu. Ainsi, un lecteur qui demande « pourquoi cette version a-t-elle changé ? », « qu’affecterait la modification de ce document partagé ? » ou « de quoi ce déploiement dépend-il réellement ? » demande la fermeture, et un lecteur qui dispose de la vue résolue ne l’obtient pas en la lisant plus attentivement.
Le même mot demande le même document sur chaque surface. --closure ici, aggrega/releaseClosure via le protocole du daemon (voir aggrega serve, « Une fermeture n’est pas le graphe ») et le mode release de l’outil describe via le protocole d’outils de l’assistant répondent tous à cette question sur une Release ; un nom de Release passé par l’un d’eux atteint la même résolution, de sorte que les trois ne peuvent pas en venir à diverger sur ce dont dépend une Release. Sur un lockfile qui ne correspond plus à ce vers quoi la Release se résout, cette commande et l’outil describe refusent avec l’arrêt pour dérive du build ; le daemon, qui sert un éditeur pendant l’édition, répond.
C’est un seul document, il est donc demandé seul. --closure sélectionne la fermeture à la place de la vue résolue, et ne peut pas être combiné avec --raw, --resolved, --output ou --ir-graph — chacun d’eux demande un document différent sur la même Release, et une commande qui accepterait deux demandes devrait silencieusement ne répondre qu’à l’une d’elles. Leur combinaison est refusée, en nommant la paire.
Il s’applique à une Release et à rien d’autre. Une entité du catalogue, un fichier d’Aggregate, un Manifest — aucun d’eux ne résout de fermeture, de sorte que la demande est refusée plutôt que de recevoir pour réponse la vue propre à ce sujet en étant abandonnée. Une demande abandonnée apparaît à l’appelant exactement comme un sujet dont la fermeture est vide.
Chaque issue est distinguée des autres. Une Release qui se résout reçoit pour réponse la liste. Un chemin de Release qui ne désigne aucun fichier est refusé, en indiquant que le fichier n’existe pas. Une Release qui existe et dont la fermeture ne peut pas être résolue est refusée en indiquant ce qui n’a pas pu être résolu et d’où provenait la référence, suivi des fichiers que le chargement du catalogue a refusés — car un fichier refusé est la raison habituelle pour laquelle une entité que la Release atteint est manquante. Un enregistrement de confiance des plugins situé à côté de la Release, qui existe et ne peut pas être lu, est refusé en indiquant ce qui n’a pas pu être lu, car une liste qui l’aurait ignoré ne signalerait aucun plugin retiré là où aucun n’a pu être vérifié. Une Release dont le lockfile ne correspond plus à ce vers quoi elle se résout est refusée avec l’arrêt pour dérive qu’affiche un build, comme le décrit Comportement en cas d’erreur, car les versions listées seraient des versions qu’aucun build de cette Release n’utilise. Une liste vide n’est jamais la réponse à aucun de ces cas : elle présenterait un chemin mal saisi, ou un workspace cassé, comme une Release qui ne dépend de rien.
Les trois niveaux de verbosité s’appliquent comme pour tout type. --list affiche uniquement les références, une par ligne, pour les pipes. Le niveau par défaut ajoute les identités résolues, la version en laquelle chaque référence s’est résolue, les documents partagés utilisés, tout mappage du Manifest dont la cible n’implémente pas le type vers lequel elle est mappée, et tout avis de dépréciation ou de retrait enregistré sur ce dont dépend la Release — dans son lockfile, contre une référence épinglée, et dans l’enregistrement de confiance des plugins situé à côté d’elle, contre un plugin rattaché dans un rôle qui renvoie un verdict d’acceptation ou de rejet — dans les termes qu’affiche aggrega build pour le même marqueur. --detail ajoute le type de chaque référence lorsque l’emplacement de la référence en a enregistré un — certaines positions d’un document disent vers quel type elles pointent et d’autres non, il est donc signalé là où il est connu au lieu d’être deviné d’après la forme du nom.
$ aggrega inspect ./release.yaml --catalog ./catalog --closure
Release: prod-release:1.0.0 Aggregate: fullstack-app Manifest: prod-manifest Environment: production
Entities (11): ./aggregate.yaml ./manifest.yaml core/compute/api-server (1.0.0) core/compute/web-ui (1.0.0) core/datastore/postgres (1.0.0) core/k8s-dns-resolver (1.0.0) db-module (1.0.0) helm-api-server-synthesized-with-artifacts:1.0.0 (1.0.0) helm-postgres-synthesized-with-artifacts:1.0.0 (1.0.0) helm-web-ui-synthesized-with-artifacts:1.0.0 (1.0.0) k8s-dns-patcher:1.0.0 (1.0.0)Lorsqu’un workspace a enregistré les versions en lesquelles se résout une Release, cet enregistrement amorce la résolution, de sorte que les versions signalées sont celles à partir desquelles ce déploiement est construit plutôt que ce que le catalogue contient aujourd’hui. Un workspace sans un tel enregistrement résout sur le catalogue tel qu’il est.
Connexion, slot et clause de sensibilité d’un rattachement
Chaque rattachement de Feature dans la vue de la Release porte une clause nommant les faits que le compilateur enregistre sur le rattachement lui-même : quel slot de rattachement il remplit, s’il manipule du matériel déclaré sensible et la FeatureRecipe qui le réalise — et, pour un rattachement écrit sur l’une des connexions du composant, la connexion sur laquelle il a été écrit. La clause se place entre le nom du rattachement et son crochet de provenance, et se lit de façon identique dans les deux formes de provenance ci-dessous.
Un rattachement écrit sur une connexion est listé sous la ligne de cette connexion dans Uses:, et non sous Features:, de sorte que Features: ne contient que les rattachements propres du composant. La ligne au-dessus nomme la connexion par son alias et le composant qu’elle atteint, et sa propre clause dit le reste :
[socket: <socket>]— le socket par lequel passe la connexion, que la ligne de la connexion ne nomme pas. Il ouvre la clause parce qu’il change la lecture du reste : la moitié slot qui suit nomme un slot que déclare le socket de la connexion, et non un slot que le composant déclare pour ses propres rattachements.[connection: <alias> through socket <socket>]— le même fait pour un rattachement dont la connexion n’a aucune ligne dans le blocUses:, qui est alors listé sousFeatures:et nomme ici sa connexion. Dans les deux cas, une connexion est nommée une fois par rattachement, jamais deux.[slot: <name>]— le rattachement remplit le slot appelé<name>. Un slot est rempli en rattachant une Feature sous le nom propre du slot, de sorte que<name>est le nom sous lequel le rattachement a été écrit, comparé aux slots déclarés : lefeaturesSchemadu Component hôte pour l’un de ses propres rattachements, et lefeaturesSchemaque déclare le socket de la connexion pour un rattachement écrit sur une connexion.[free]— le rattachement ne remplit aucun slot déclaré : le Component résolu ne déclare aucun slotfeaturesSchemade ce nom. Il s’agit d’un constat, pas d’un diagnostic. Un rattachement de forme libre est accepté, et un opérateur qui souhaite l’interdire l’exprime sous forme de politique de gouvernance plutôt que de compter sur l’outil pour le refuser.[sensitive]— le rattachement manipule du matériel qu’un auteur a déclaré sensible, parce que la Feature rattachée déclare une feuille sensible, parce que le slot qu’il remplit déclaresensitive: true, ou les deux.[realization: <name>:<version>]— la FeatureRecipe que le Manifest de la Release lie pour le rattachement : par le nom propre du rattachement lorsque le Manifest mappe ce nom — pour un rattachement écrit sur une connexion, l’alias et le slot joints par un point —, sinon par son type de Feature. C’est la réalisation avec laquelle un build des mêmes documents rend le rattachement, et la même valeur que le graphe compilé porte sur le rattachement sous la formerealization(voir--ir-graph), de sorte que cette vue et le graphe ne peuvent pas en nommer de différentes. Elle vient en dernier dans la clause.
Lorsque plusieurs faits s’appliquent, ils partagent une clause. core/storage/s3-object-store déclare un slot secret_access_key marqué sensitive: true, de sorte qu’un identifiant rattaché sous ce nom signale les deux faits, tandis qu’une Feature rattachée sous un nom pour lequel le Component ne déclare aucun slot ne signale ni slot ni sensibilité. Avec un Manifest qui mappe chaque type de Feature vers une FeatureRecipe, chaque ligne nomme aussi sa réalisation :
Features: - secret_access_key (core/generated-secret:1.0.0) [slot: secret_access_key, sensitive, realization: generated-secret:1.0.0] [explicit] - cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]Un composant dont le socket models déclare un slot credential marqué sensitive: true, et qui relie une connexion sous l’alias gpt qui le remplit, liste ce rattachement sous la connexion — à côté d’un identifiant qui lui est propre, qui reste sous Features: :
Uses: gpt → model - gpt.credential (feature.conn/token:1.0.0) [socket: models, slot: credential, sensitive, realization: conn-token-compose:1.0.0] [explicit] Features: - db_password (feature.conn/token:1.0.0) [slot: db_password, sensitive, realization: conn-token-compose:1.0.0] [explicit]Un rattachement écrit sur une connexion ne signale jamais [free] : un socket n’admet que les slots qu’il déclare, et une connexion portant tout autre nom est refusée au chargement du build.
La clause est entièrement omise lorsqu’aucun des faits ne s’applique, et chaque moitié est omise indépendamment :
- L’absence de moitié socket ou connexion signifie que le rattachement a été écrit sur le bloc propre du composant, ou l’a atteint depuis une portée plus large ou par expansion pilotée par les annotations.
- L’absence de moitié slot signifie que l’ensemble des slots déclarés du Component hôte n’a pas pu être résolu — par exemple, son type ne correspond à aucune entité du catalogue. C’est délibérément distinct de
[free]:[free]répond « aucun slot de ce nom n’est déclaré », tandis qu’une moitié absente signifie que la question n’a pas du tout pu recevoir de réponse. - L’absence de
sensitiveindique qu’aucune déclaration n’a marqué le rattachement. C’est plus restreint qu’un verdict selon lequel le rattachement ne porte rien de secret ; l’axe signale des déclarations, et rien n’est déduit du nom d’un champ ou de sa valeur. - L’absence de moitié réalisation signifie que le Manifest ne lie le rattachement à aucune FeatureRecipe que contient le catalogue.
Un slot dont le nom déclaré est littéralement free est lui aussi rendu comme [free], impossible à distinguer d’un rattachement de forme libre — rien ne réserve ce mot dans l’espace de noms des slots.
Grammaire du crochet de provenance de l’IR
Chaque rattachement de Feature dans la vue de la Release porte un crochet de provenance. Le crochet peut prendre une forme compacte (un crochet par Feature lorsque la provenance du rattachement est uniforme sur toutes les feuilles) ou une forme par feuille (un crochet par feuille lorsque les feuilles du rattachement proviennent de sources hétérogènes). Il existe trois corps de crochet ; ils s’appliquent de façon identique aux deux formes.
Les trois corps de crochet
-
[explicit]— le rattachement de Feature est déclaré par l’auteur. L’Aggregate ou la Release a explicitement nommé la Feature sur le nœud concerné. Les rattachements explicites sont la source de plus haute priorité ; ils l’emportent toujours sur les contributions pilotées par les annotations sur la même feuille. -
[annotation: <key> from <source>]— le rattachement de Feature est piloté par les annotations. Le compilateur l’a synthétisé parce qu’une annotation sur<source>correspondait à une liaison du Manifest déclarant cette Feature.<key>est la clé d’annotation qui a déclenché la liaison (par ex.business.aggrega.ai/team) ;<source>est l’entité qui portait l’annotation (aggregate,release,componentoumanifest). Le rattachement synthétisé est structurellement identique à un rattachement explicite — le rendu en aval les traite de la même façon —, mais le crochet de provenance les distingue afin que le débogage reste décidable. -
[explicit; overrides annotation: <key> from <source>]— une forme par feuille qui se déclenche lorsqu’une déclaration explicite de l’auteur sur une feuille supprime une contribution d’annotation qui aurait sinon défini la même feuille. La composition inter-côtés produit ce cas : une annotation de l’Aggregate peut fournir le piliervalues:d’une Feature, une annotation de la Release fournit son pilierinfra:, et une déclaration explicite de la Release sur la même Feature remplace une feuille infra. Le crochet de la feuille enregistre à la fois l’auteur explicite et l’annotation supprimée ; l’annotation supprimée ne contribue pas à la sortie rendue, mais sa présence apparaît dans la vue inspect afin que l’opérateur puisse voir quelle annotation a été remplacée et où.
Forme compacte et forme par feuille
Le compilateur choisit entre le rendu compact et le rendu par feuille en parcourant la provenance par feuille du rattachement et en vérifiant son uniformité. La provenance d’un rattachement est uniforme lorsque chaque feuille renseignée (dans les piliers values: et infra: de la Feature) partage la même origine (explicite ou annotation), la même clé d’annotation lorsqu’elle est pilotée par les annotations, la même entité source, et qu’aucune feuille ne porte de marqueur « overrides annotation ». Lorsque la provenance est uniforme, le compilateur émet un crochet par rattachement :
- core/rate-limiter [annotation: business.aggrega.ai/team from aggregate]Lorsque la provenance diverge — un cas typique est la composition inter-côtés, où une annotation de l’Aggregate fournit values: et une annotation de la Release fournit infra: sur la même Feature —, le compilateur émet un crochet par feuille renseignée :
- core/pii-redaction values.fields_to_mask: ["ssn", "card_number"] [annotation: compliance.aggrega.ai/data-class from aggregate] values.classifier_endpoint: "redact-v2" [explicit; overrides annotation: compliance.aggrega.ai/data-class from aggregate] infra.audit_bucket: "s3://..." [annotation: compliance.aggrega.ai/audit-bucket from release]L’ordre de parcours est d’abord le pilier values (dans l’ordre de l’auteur), puis le pilier infra (selon la même discipline). Le préfixe du pilier (values. / infra.) et le chemin pointé à l’intérieur du pilier indiquent exactement quelle feuille chaque crochet annote.
Valeurs déclarées sensibles
Une feuille dont le schéma déclare sensitive: true affiche le texte fixe <redacted> à la place de sa valeur. La clé, le préfixe du pilier et le crochet de provenance sont tous conservés — seule la valeur est remplacée —, de sorte que la présentation indique toujours quelles feuilles porte une entité et d’où provient chacune. Deux surfaces lisibles sont concernées : le bloc Values: par nœud d’un Aggregate, et le bloc de rattachements par feuille d’une Release résolue — y compris un rattachement écrit sur une connexion, affiché sous la ligne de cette connexion, qui masque exactement les feuilles que la même Feature masque lorsque le composant la détient lui-même. Le graphe compilé d’une Release sous --ir-graph masque les mêmes feuilles sous la forme structurée décrite dans Sortie lisible par machine.
Components: app (type: core/app) Values: appName: demo dbPassword: <redacted> tuning.poolSize: 25 tuning.adminToken: <redacted>Seule une feuille déclarée est masquée, et la clause [sensitive] au niveau du rattachement n’est pas une instruction de masquage : elle dit que le rattachement manipule du matériel secret, pas lesquelles de ses feuilles le portent. Les localisateurs publiés d’une Feature d’identifiant — le nom de la ressource et la clé de données — sont publics et sont délibérément laissés non déclarés dans le catalogue de la bibliothèque standard, de sorte qu’ils s’affichent en clair à côté du matériel qui ne l’est pas :
- credentials (feature.test/db-credential) values.secretName: db-creds [explicit] values.literalPassword: <redacted> [annotation: feature.test/pw from aggregate.yaml:components.app.annotations.feature.test/pw]Rien n’est déduit du nom d’un champ : un champ appelé password qui ne porte aucune déclaration affiche sa valeur, et un champ déclaré appelé key ne l’affiche pas. Le masquage porte sur ce que l’outil affiche ; il n’atteint jamais un artefact rendu, et dist/ est émis exactement tel que le rendu l’a produit. Le mot-clé et la limite complète de ce que sa déclaration permet sont décrits dans vocabulary/compact-form-authoring.md, « Déclarer une feuille sensible ».
Afficher les valeurs masquées
--unredacted affiche les valeurs déclarées sensibles au lieu de les masquer, sur chaque surface d’inspect à la fois — les présentations lisibles ci-dessus comme le graphe compilé d’une Release. Il existe parce que la valeur masquée est parfois justement celle que l’on examine : un identifiant provenant du mauvais rattachement paraît identique au bon lorsque les deux apparaissent masqués.
Sa portée est la commande à laquelle il est passé. aggrega build et aggrega validate l’acceptent aussi, où il atteint le graphe que --ir-graph renvoie et rien d’autre, et le refusent lorsqu’aucun graphe n’a été demandé. aggrega build --trace-unredacted est la même idée appliquée aux fichiers de trace du build, et aucun des deux flags du build n’atteint la sortie de l’autre ; un artefact rendu sous dist/ n’est affecté par aucun d’eux, car il est émis exactement tel que le rendu l’a produit, quoi qu’on passe.
Tout ce que la sortie atteint porte alors ces valeurs en clair — un terminal, un pipe, un fichier, un enregistrement d’écran, un rapport de bug collé. Contrairement aux fichiers de trace, qui s’ouvrent chacun sur un en-tête indiquant qu’ils ont été capturés sans masquage, la sortie sur un terminal ne porte aucune marque de ce genre : seule la ligne de commande indique qu’il a été passé.
Quand recourir à inspect
- Déboguer « pourquoi cette Feature est-elle là ? » — les rattachements pilotés par les annotations sont invisibles dans les fichiers YAML de l’Aggregate et de la Release (les annotations y figurent, mais les rattachements de Feature qu’elles synthétisent n’existent que dans l’IR). Inspect les fait apparaître avec leur provenance.
- Vérifier l’héritage de schéma —
aggrega inspect <ComponentName>affiche le schéma fusionné après la résolution de la chaîneextends:; le fichier rédigé seul ne montre que le delta local. - Diagnostiquer les surprises de la composition inter-côtés — lorsqu’une annotation de l’Aggregate et une annotation de la Release fournissent toutes deux des charges utiles de pilier sur la même Feature, les feuilles résolues peuvent être difficiles à reconstituer mentalement. La forme de crochet par feuille rend la résolution explicite.
- Vérification avant déploiement —
aggrega inspect ./prod-release.yamlliste chaque Feature sur chaque Component avant queaggrega buildne produise les artefacts ; l’opérateur peut confirmer que la topologie correspond à l’intention avant de committer les manifestes rendus dans GitOps.
Pour les mécanismes sous-jacents — comment les annotations se propagent en cascade, comment la partition entre côté et pilier achemine les valeurs d’annotation vers les piliers de la Feature, et comment la discipline selon laquelle le rattachement explicite l’emporte interagit avec les contributions pilotées par les annotations —, voir providers/well-known-annotations.md et entities/manifest.md, « Liaisons de Feature pilotées par les annotations ».
Synopsis
aggrega inspect [identifier] [flags]Description
Render a readable view of any Aggrega entity — a catalog entity by name, anauthored entity file by path, an entity published in a registry, or afully-resolved Release.
It answers "what does this entity actually resolve to?": which entities extendwhich bases, which Recipe maps to each type, which Features attach to each node,and where each Feature's contributions came from.
A single argument routes by its shape. A path — anything starting with ./, ../or /, or ending in .yaml or .yml — is read as a file and inspected by its ownkind: header. A registry reference — oci://<host>/<repository>:<tag>, or@<digest> in place of :<tag> — is read from the registry that publishes it.Anything else is looked up by name in the catalog search stack: theworkspace's own, or, with --release, the one the workspace configurationgives that Release, so a name several catalog variants declare, one perRelease, resolves to the variant that Release builds with.
A registry reference shows the entity exactly as it was published: unpackedfrom the archive its kind is published as where it is one, and rendered by thesame view a file of that kind gets. Reading it reaches the network, using thecredentials this machine holds for that registry, and an offline workspacerefuses it. The fetched bytes are checked against the digest the artifact'sown manifest records for them, which establishes that they are the bytes thatmanifest names and nothing more: no signature attached to the artifact isverified, no withdrawal recorded against it is reported, and nothing iswritten — no cache entry and no lockfile.
Three verbosity levels apply to every kind: --list for identifiers only, thedefault for a structured overview, and --detail for full field bodies. --listand --detail are mutually exclusive. Resolution depth has its own pair, --rawfor the entity exactly as authored and --resolved for the kind's full depth,also mutually exclusive.
Note that --raw reproduces the file as written, so a value the author declaredsensitive appears as authored. That is what as-authored means; handle suchoutput as you would the entity file itself. --output yaml reproduces the filethe same way for every kind, a Release included.
A Release answers two further questions, and each has its own flag becauseneither answer contains the other. --ir-graph asks for the IR graph a Releaseresolves to — what the Release looks like, as JSON on stdout in addition towhatever else this command produces. --closure asks for the Release's dependencyclosure — every catalog entity it reaches and the version each resolved to,which is what was pulled in to build the Release. An entity can be reachedwithout appearing as a node, and a node does not carry the version its typeresolved to, so holding one of the two is not holding the other.
--ir-graph is orthogonal to --output, which picks the format of the command'sown view. Values an author declared sensitive are withheld from the graph, asthey are from the readable layouts. Pass --unredacted to print them instead.Options
| Option | Par défaut | Description |
|---|---|---|
--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. |
--closure | false | Signale la fermeture des dépendances de la Release — chaque entité du catalogue qu’elle atteint, à la version en laquelle chacune s’est résolue — à la place de la vue des nœuds résolus. S’applique à une Release, le seul type qui résout une fermeture ; tout autre type refuse la demande au lieu de l’abandonner silencieusement. |
--color | auto | Coloriser la sortie : auto|always|never. |
--detail | false | Rendre les corps complets des champs. |
--flat | false | Rendre une entité arborescente (Aggregate, Release) sous forme de liste plate, chaque nœud étant préfixé par son chemin pointé complet. Sans effet sur les types tabulaires. |
--ir-graph | false | Écrire aussi sur stdout, en JSON, le graphe IR que cette exécution a calculé, 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. S’applique à une Release, le seul type qui se résout en un graphe ; tout autre type refuse la demande au lieu de l’abandonner silencieusement |
--list | false | Rendre uniquement les identifiants. |
--no-color | false | Désactiver la sortie colorisée (alias de —color=never). |
--output, -o | text | Format de sortie : text|yaml. |
--plugin | — | Chemin du système de fichiers vers un artefact <file.wasm> brut ; détermine et affiche les fonctions hôtes qu’il importe, avant que aggrega plugin sync ne les enregistre dans une entité Plugin. N’accepte aucun argument d’identifiant. |
--raw | false | Rendre l’entité telle que rédigée, sans résolution. |
--release | — | Rechercher un nom du catalogue dans les termes de ce fichier de Release : à travers les répertoires de catalogue que la configuration du workspace attribue à cette Release, avec —catalog ajouté en tête. S’applique à un nom ; un fichier ou une référence de registry est inspecté tel quel et le refuse. Un chemin relatif se résout 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 |
--resolved | false | Rendre l’entité entièrement résolue. |
--show-implements | false | Pour une Recipe ou une FeatureRecipe, résoudre spec.implements par rapport au catalogue et rendre le Component ou la Feature lié. |
--unredacted | false | Afficher 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 — porte alors ces valeurs en clair. |