Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

aggrega serve

aggrega serve esegue Aggrega come daemon compiler-as-service di lunga durata per l’integrazione con gli IDE. Comunica tramite JSON-RPC 2.0 su stdin/stdout e mantiene lo stato del catalog-resolver, della parse-cache e della diagnostica tra una richiesta e l’altra, così le operazioni dell’editor ricevono un riscontro in meno di un secondo invece di pagare l’intero costo di caricamento del catalogo a ogni battitura.

Il daemon viene normalmente avviato come sottoprocesso da un’estensione dell’editor, non eseguito a mano. Un’estensione per VS Code è il client di riferimento; altri editor possono integrarsi parlando lo stesso protocollo.

Il protocollo

Il protocollo di trasmissione è JSON-RPC 2.0 con framing Content-Length, nel namespace di metodi aggrega/. Volutamente non è il Language Server Protocol — Aggrega ha operazioni di dominio (una query sul grafo IR, un segnale di invalidazione della cache) per cui LSP non ha equivalenti. Un’estensione dell’editor traduce tra le richieste LSP dell’editor e questi metodi aggrega/*; i valori di posizione, intervallo e location nella forma di LSP vengono riutilizzati dove si adattano.

Due metodi mantengono i loro nomi $/ standard del protocollo invece di essere rinominati nel namespace aggrega/, perché entrambi riguardano il trasporto, non hanno alcun significato per Aggrega e un client che parla già il protocollo li gestisce senza aggiungere nulla: $/cancelRequest, che interrompe una richiesta di cui il client non vuole più la risposta, e $/progress, con cui il daemon riporta un’operazione lunga mentre è in corso. Entrambi sono descritti più avanti.

🔴 Ogni richiesta qui sotto contiene workspaceRoot, il percorso assoluto del workspace su cui agisce, e questo non viene ripetuto per ogni metodo. Tre non lo contengono, perché il loro oggetto non è un workspace: aggrega/initialize, aggrega/getSchema e aggrega/scaffoldEntity — tranne che aggrega/scaffoldEntity, quando scrive o elenca un esempio eseguibile, ne nomina uno. Vedi Ogni richiesta nomina il workspace a cui si riferisce per che cosa ottiene una richiesta che non ne nomina nessuno, e Dichiarare il workspace per cui vuoi ricevere la diagnostica per dove va la diagnostica inviata dal daemon.

Le forme campo per campo sono pubblicate come schema, e il riferimento delle forme di trasmissione è dove leggerle. Quella pagina riporta l’oggetto dei parametri di ogni metodo, ogni risultato e ogni payload di notifica — ogni campo con il suo tipo, se è obbligatorio e che cosa contiene — insieme a tre proprietà che valgono sull’intera superficie anziché per singolo metodo: i due campi che ogni richiesta ammette oltre a quelli dichiarati dal proprio metodo, cioè workspaceRoot qui sopra e il workDoneToken di Osservare un’operazione lunga; il fatto che un oggetto params contenente una chiave non accettata dal suo metodo viene rifiutato, con l’insieme accettato nominato nel rifiuto; e dove una collezione assente arriva sul filo come null anziché come collezione vuota. È generata da quello schema, quindi cambia quando cambia il contratto.

Questa pagina contiene il protocollo, quella contiene le forme, e sono pensate per essere lette insieme. Qui: il framing, a che cosa serve ogni metodo, fin dove arriva, che cosa scrive, quali rifiuti solleva e perché, i codici di errore e che cosa fare per ciascuno. Lì: che cosa mettere sul filo, chiave per chiave. Così l’elenco qui sotto nomina ogni metodo e dice che cosa significa interrogarlo, e l’elenco dei campi per la richiesta che stai componendo si trova nel riferimento accanto.

Richieste:

  • aggrega/initialize — handshake. Negozia la codifica delle posizioni (il server preferisce UTF-8, poi UTF-16, poi UTF-32, e usa UTF-16 come predefinita), riceve il workspace che dichiari per la diagnostica inviata e riporta la radice di quel workspace, il livello di configurazione da cui sono state risolte le sue impostazioni e il marcatore che lo ha risolto. La risposta contiene anche version, la versione del binario che risponde: lo stesso valore che aggrega version riporta per quel binario. Descrive il processo in esecuzione, quindi una volta sostituito il file da cui il daemon è stato avviato — con una ricompilazione nello stesso percorso, ad esempio — version nomina ancora il daemon in esecuzione mentre interrogare il file nomina il suo sostituto; leggilo qui quando la domanda è con quale versione stai parlando. workspaceRoot è facoltativo e dichiara un workspace invece di agire su di esso — vedi Dichiarare il workspace per cui vuoi ricevere la diagnostica. Invia capabilities.window.workDoneProgress: true per indicare che il tuo client sa gestire le notifiche di avanzamento; capabilities.workDoneProgress nella risposta lo ripete, e il campo è assente per un client che non ha dichiarato nulla. Vedi Osservare un’operazione lunga.
  • aggrega/validate — valida il contenuto di un file; restituisce la diagnostica. release è un percorso relativo alla radice del workspace che nomina la Release rispetto a cui validare — lo stesso valore che accetta aggrega/irGraph, e lo stesso che accetta aggrega build --release quando viene eseguito dalla radice. È facoltativo e determina fin dove arriva la risposta: se nomini una Release, i controlli che ne richiedono una vengono eseguiti rispetto a essa — un’entità di catalogo viene controllata come singola entità nei termini di quella Release, e ogni altro documento rispetto alla chiusura delle dipendenze di quella Release; se lo ometti, la risposta copre ciò che si può esigere dal documento da solo, e contiene checked per indicarlo. Un valore presente ma malformato viene rifiutato in entrambi i casi — un percorso assoluto, o uno che si risolve fuori dalla radice del workspace, viene respinto invece che risolto. Vedi Validazione dal vivo.
  • aggrega/diagnostics — restituisce i risultati mantenuti per un file. Se all’arrivo della richiesta è in corso una validazione dello stesso file, la risposta la attende e riporta ciò che ha trovato, così la risposta non è mai un certificato di buona salute per un file in cui il daemon sta ancora cercando problemi. Vedi Chiedere la diagnostica mentre è in corso una validazione.
  • aggrega/hover — contenuto hover per l’entità in una posizione. release è facoltativo e risponde nei termini di quella Release — vedi Rispondere nei termini di una Release.
  • aggrega/completion — candidati di completamento in una posizione. Dove il cursore nomina un’entità per tipo — il type di un componente, il type del collegamento di una Feature, un valore extends:, l’implements: di una Recipe o di una FeatureRecipe — i candidati sono i nomi di quel tipo dichiarati dai documenti del tuo workspace e, per un Component o una Feature, anche i nomi dichiarati dalle tue catalog_dirs configurate, ciascuno offerto una volta e in ordine di nome. A un workspace che prende i suoi Components e le sue Features da un catalogo vengono quindi offerti questi, non solo ciò che ha scritto da sé. Recipes e FeatureRecipes, offerte come valore di una mappatura del Manifest, provengono dai documenti del workspace stesso. Un’entità presente solo nella cache degli artefatti o in un registry non viene offerta: rispondere a un completamento non scarica mai nulla. release è facoltativo e risponde nei termini di quella Release — vedi Rispondere nei termini di una Release.
  • aggrega/resolve — risolve l’entità referenziata in una posizione (vai alla definizione). release è facoltativo e risponde nei termini di quella Release — vedi Rispondere nei termini di una Release.
  • aggrega/findReferences / aggrega/findImplementations. Ciascuno accetta un release facoltativo e risponde nei termini di quella Release — vedi Rispondere nei termini di una Release.
  • aggrega/irGraph — il grafo IR compilato per una Release, per l’introspezione nell’editor. release è un percorso relativo alla radice del workspace che nomina una Release al suo interno — lo stesso valore che accetta aggrega build --release quando viene eseguito dalla radice. Qualsiasi altra forma viene rifiutata con l’errore standard invalid-params che indica che cosa inviare invece: un percorso assoluto, un percorso che si risolve fuori dalla radice del workspace — sia che ne esca così come è scritto, sia che ne esca tramite un link, verso il file o verso una directory lungo il percorso — e un valore vuoto vengono tutti respinti invece che risolti, così una richiesta non riporta mai su un file che il workspace non contiene. Una Release che la configurazione del tuo workspace nomina, come build.authoring_release o come chiave di workspace.releases, è contenuta nel workspace ovunque si trovi il suo file, quindi un link all’interno del workspace che porta a essa viene accettato, così come aggrega/releaseCandidates la elenca. Una directory di catalogo letta dalla Release che non può essere percorsa — una che esiste e non può essere letta, ad esempio — viene rifiutata come la rifiuta aggrega inspect, prima che venga letta qualsiasi altra cosa: l’errore è 1004 entity-not-resolvable, il suo messaggio è il report che la riga di comando stampa per quella directory, su una riga ([CATALOG_ERROR] <directory>: catalog load: …), e nessun grafo viene tracciato sulle directory rimanenti. Una directory elencata dalla configurazione del workspace che non è una directory — dove non esiste nulla, ad esempio — viene rifiutata allo stesso modo e nello stesso momento, 1004 entity-not-resolvable, con come messaggio il rifiuto che le dà ogni comando, che nomina la voce, il file di configurazione e la riga che la elencano e l’impostazione (Da dove vengono lette le entità locali). Una directory di catalogo che contiene un link che esce dalla directory entro cui le sue letture devono restare — un documento o una directory collegati da altrove, sotto una directory di catalogo all’interno del workspace o sotto una che la configurazione nomina fuori da esso — viene rifiutata allo stesso modo e nello stesso momento, con 1004 e la frase propria della condizione che nomina il link e dove porta: nulla viene letto attraverso un tale link, e un grafo tracciato senza di esso potrebbe risolvere al suo posto un’altra entità con lo stesso nome. Lo stesso vale per un link che esce dai documenti accanto alla Release, dove la Release nomina il suo Aggregate o il suo Manifest per identità. Un file che la Release, il suo Manifest o una Release che essa estende nomina tramite un percorso — aggregate:, manifest:, extends: o un $import: dei parameters — e che esce dal workspace, così come è scritto o tramite un link, viene rifiutato con la frase propria della condizione (fatal-halts.md §«A reference to another file leads out of the directory it must stay inside (Un riferimento a un altro file esce dalla directory entro cui deve restare)»), con i dati dell’errore che lo collocano sulla chiave della Release che ha portato al file, e nulla viene letto da quel file; una Release che la configurazione nomina fuori dal workspace è vincolata allo stesso modo alla directory che la contiene, quindi viene rifiutato anche un percorso, scritto da essa o da una Release a cui porta la sua catena, che esce da quella directory. Nota che aggrega/releaseCandidates risponde con percorsi assoluti, quindi un client che alimenta una superficie con l’altra converte tra le due forme. Il fatto che questo parametro rifiuti una grafia che i parametri per documento file e uri accettano è deliberato, e Quali grafie accetta un parametro che invii spiega che cosa lo decide. Il grafo nasconde ogni valore che un autore ha dichiarato sensibile, esattamente come lo nasconde --ir-graph sulla riga di comando: ciascuno è sostituito dal marcatore descritto in aggrega-inspect «Output leggibile da una macchina», e tutto il resto viene riportato così come il compilatore lo ha registrato. unredacted: true chiede quei valori in chiaro — la grafia del protocollo per il --unredacted della riga di comando, e l’unico modo per chiederli; se è assente o false, la risposta li nasconde. Tutto ciò che la risposta raggiunge contiene allora i valori in chiaro, quindi un client li chiede solo dove lo ha fatto la persona che lo usa.
  • aggrega/build — compila una Release e ne scrive gli artefatti nella directory di output del workspace, la stessa directory in cui scrive aggrega build quando viene eseguito dalla radice del workspace. release ha lo stesso contratto descritto sopra. Esegue il rendering con tutti i controlli attivi, quindi una divergenza su cui una build da riga di comando si fermerebbe la ferma anche qui. Una directory di catalogo letta dalla Release che non può essere percorsa — una che esiste e non può essere letta, ad esempio — viene rifiutata come la rifiuta aggrega build, prima che venga scritto alcunché: nessun artefatto, e nessun lockfile quando è impostato autoPull. Lo stesso vale per una directory elencata dalla configurazione del workspace che non è una directory, con le parole con cui la rifiuta aggrega build (Da dove vengono lette le entità locali). Il rifiuto è quello che aggrega/irGraph dà per la stessa directory, 1004 entity-not-resolvable con il rapporto della riga di comando su una sola riga, e un link che esce dalle letture di una directory di catalogo, o dai documenti accanto alla Release, viene rifiutato come lo rifiuta aggrega/irGraph, senza scrivere nulla. La risposta indica la outputDirectory in cui ha scritto e i files che ha scritto, ciascuno relativo a quella directory e in ordine, insieme alle eventuali notices sollevate dall’esecuzione; i rilievi che portano una posizione nel documento viaggiano invece su aggrega/publishDiagnostics. A una Release che rifiuta durante il rendering si risponde con quel rifiuto nelle parole del compilatore, ogni causa inclusa, e il rifiuto viene pubblicato dove punta — vedi Un rifiuto sollevato durante il rendering. Quando era impostato autoPull, la risposta contiene anche dependencyResolution, lo stesso rapporto con cui risponde aggrega/resolveDependencies, così un client che ha riempito le dipendenze come parte della build legge che cosa è stato fissato senza chiederlo di nuovo — e da dove la risoluzione di questa build ha preso ogni riferimento, un fatto su quell’esecuzione che il lockfile non registra. Ogni notifica porta la class della superficie che l’ha sollevata — deprecation, catalog, catalog-lint, extends, release-composition, oppure dependency-resolution per una riga sollevata dalla risoluzione delle dipendenze descritta più sotto — e una class vuota quando il daemon non ha un nome per quella superficie, che un client mostra come il semplice text invece di tentare di indovinare la corrispondenza più vicina. I file che la scrittura trova nella directory di output, o in una directory al suo interno in cui ha scritto un file o che ha attraversato, e che questa build non ha scritto vengono lasciati dove sono e nominati in un’unica notifica dopo quelle dell’esecuzione stessa, sotto una class vuota, con la frase con cui aggrega build stampa il proprio avviso — vedi File che la build non ha scritto; files non li nomina mai. outputParent dice dove vanno gli artefatti all’interno del workspace, e il suo nome è tutto ciò che significa: è la directory all’interno della quale viene creata la directory di output, quindi inviare docs scrive gli artefatti in docs/dist anziché in docs stessa — esattamente ciò che produce una build eseguita in docs da un terminale. Se lo ometti, la build scrive dove scrive un’esecuzione nella radice del workspace. Si legge in modo diverso dall’outputDir che accettano le altre richieste di scrittura qui, e di proposito: quelle nominano la directory in cui si scrive, questo nomina la directory madre di quella, e i due hanno nomi diversi perché sono cose diverse. Resta comunque una destinazione all’interno del workspace, quindi un valore assoluto, uno che risale fuori dalla radice e uno che ne esce tramite un link — una directory collegata fuori dalla radice, o una directory non ancora creata al di sotto di essa — vengono rifiutati anziché risolti. Anche la directory di output creata al suo interno, e ogni file che la build vi scrive, sono vincolati al workspace: quando uno di essi esce dal workspace tramite un link, la build viene rifiutata con 1004 e la frase propria della condizione, che nomina il link e dove porta, e nulla viene svuotato o scritto. autoPull risolve le dipendenze della Release prima del rendering, la stessa risoluzione che esegue aggrega/resolveDependencies, ed è disattivato a meno che una richiesta non lo chieda, in linea con il default della riga di comando stessa; senza di esso, una Release che non ha un lockfile viene rifiutata con l’errore lockfile-absent, che indica che cosa eseguire. Con autoPull impostato, questa richiesta raggiunge i registry e scrive il lockfile — vedi Raggiungere un registry e scrivere. Una richiesta che risolve prima esegue comunque il rendering della Release una sola volta: scoprire quali riferimenti remoti consuma una Release è già di per sé un rendering, quindi la risoluzione ha già eseguito il rendering di ciò che riguarda la build, e alla build si risponde da quel rendering anziché ripeterlo. policyInput nomina una directory all’interno del workspace, relativa alla sua radice, in cui la build scrive anche il payload che ogni ruolo di governance consegna a un plugin collegato lì — i file che scrive aggrega build --policy-input, con gli stessi nomi — sia che la build termini sia che si fermi; le notices della risposta dicono poi quanti ne sono stati scritti e nominano ogni ruolo per cui non è stato scritto alcun file, sotto una class vuota. Su una richiesta che fallisce, i file scritti sono su disco e quel resoconto non è nella risposta: l’envelope di errore porta soltanto il rifiuto. È una destinazione, quindi un valore assoluto o uno che risale fuori dal workspace viene rifiutato prima che venga eseguito alcunché.
  • aggrega/buildPreview — riporta che cosa scriverebbe una build della Release, senza scriverne nulla. release ha lo stesso contratto descritto sopra. Esegue lo stesso calcolo di aggrega/build, con gli stessi controlli, quindi una Release o verrebbe rifiutata da entrambe o viene riportata da entrambe — ed è questo che rende la scelta tra le due una scelta sull’output anziché sul rigore. Una directory di catalogo letta dalla Release che non può essere percorsa, o che contiene un link che esce dalla directory entro cui le sue letture devono restare, viene rifiutata allo stesso modo, prima che venga eseguito alcun rendering, e così pure una directory elencata dalla configurazione del workspace che non è una directory, come in aggrega/build. La risposta contiene files, i nomi relativi all’output che una build emetterebbe, in ordine, insieme alle eventuali notices; non c’è outputDirectory, perché non è stato scritto nulla da nessuna parte da poter nominare. A una Release che rifiuta durante il rendering si risponde, e il rifiuto viene pubblicato, esattamente come fa aggrega/build. Rifiuta autoPull con un errore invalid-params che indica che cosa inviare invece: riempire le dipendenze scrive il lockfile, e questa richiesta non scrive alcun lockfile. Non raggiunge alcun registry. policyInput è l’unica scrittura che esegue, e solo quando viene inviato: scrive i payload di governance in quella directory esattamente come fa aggrega/build — i file che scrive aggrega build --dry-run --policy-input — lasciando intatti la directory di output e il lockfile, con lo stesso resoconto nelle notices e lo stesso limite: su una richiesta che fallisce, i file scritti sono su disco e il resoconto non è nella risposta.
  • aggrega/resolveDependencies — risolve le dipendenze di catalogo e di sorgente della Release nella cache, fissa gli input esterni consumati dal suo rendering nello store indirizzato per contenuto e scrive il suo lockfile. release è un percorso relativo alla radice del workspace, lo stesso valore che accetta aggrega/irGraph, rifiutato nelle stesse forme. upgrade scarta i pin registrati e risolve di nuovo, portando ogni dipendenza alla versione più alta disponibile; targets limita questo ai riferimenti di entità che nomina, mantenendo ogni altro pin. verify confronta la risoluzione registrata con quella che questa richiesta eseguirebbe senza di esso, rispettando allo stesso modo i pin registrati, e non scrive alcun lockfile, record di attendibilità dei plugin o entity.lock — la cache viene letta e riempita come lo sarebbe senza di esso — rispondendo con verified: true e il toolchain registrato dal lockfile. verify viene rifiutato come parametri non validi insieme a upgrade, insieme a targets e insieme a pinSources, qualunque valore abbia, prima che venga risolto qualsiasi cosa o riportato alcun avanzamento: un upgrade scarta i pin che un verify esiste per rispettare, i target nominati vengono risolti di nuovo solo da un upgrade, e pinSources decide se una risoluzione registra i pin che mancano a un entity.lock o rifiuta a causa loro, e nessuna delle due cose riguarda un confronto che non scrive alcun entity.lock. La riga di comando e lo strumento dell’assistente rifiutano le stesse coppie. La risposta nomina il lockfile che ha scritto o con cui ha confrontato e ogni riferimento che ha fissato, in entities, libraries e plugins, ogni voce con la version a cui si è risolta e la sua source — da dove questa esecuzione ha preso il riferimento, con la parola che aggrega pull --detail stampa per la stessa risoluzione: fetched-fresh, cache-reuse, local, in-binary o external — insieme a sourceArtifacts, trustedPlugins, externalInputs — quanti input esterni il lockfile fissa al termine dell’esecuzione, contando sia quelli mantenuti sia quelli scoperti da questa esecuzione — e le eventuali notices sollevate dalla risoluzione. 🔴 Una risposta riuscita non significa di per sé che il fissaggio degli input esterni sia completo. Dove l’esecuzione ha fissato ogni dipendenza ma non è riuscita a determinare fino in fondo quali input esterni consuma la Release, risponde con incompleteExternalInputs indicando che cosa ha interrotto la scoperta, e risponde comunque con un successo — i pin delle dipendenze sono completi e su disco, quindi segnalare l’intera richiesta come fallita ti direbbe di rifare un lavoro che è già corretto. Leggi quel campo prima di considerare un lockfile completamente fissato: è assente quando non è rimasto nulla da scoprire, quindi la sua presenza è il segnale. Non esiste un parametro per la directory di catalogo: lo stack di ricerca è quello configurato dal workspace. Questa è l’unica richiesta di fissaggio della sessione per una Release, ed è qui che vengono fissati anche gli input esterni — quali URL consuma un rendering dipende da ciò che renderizza, quindi questa richiesta esegue il rendering della Release per scoprirlo, e una richiesta di build viene poi servita da ciò che ha registrato. Una Recipe o una FeatureRecipe compilata dalla Release il cui entity.lock non registra alcun pin per un input letto dall’entità fa rifiutare la richiesta, che nomina aggrega pin e ogni input non registrato; pinSources: true esegue invece quel passaggio di pin su quelle entità, scrivendo l’entity.lock accanto a ciascuna — lo stesso passaggio che esegue aggrega/pin, scrivendo gli stessi byte. Se assente, pinSources segue il pin_sources_at_pull del workspace; se inviato, sovrascrive quell’impostazione in entrambe le direzioni, quindi false rifiuta anche in un workspace configurato per fissare. Questa richiesta raggiunge i registry e scrive — vedi Raggiungere un registry e scrivere.
  • aggrega/pin — registra, nell’entity.lock accanto a una Recipe o FeatureRecipe, il pin di contenuto per ogni input che l’entità legge al di fuori del proprio documento: una sorgente remota le cui coordinate sono scritte per intero, un file importato da una voce artifacts e ogni file che una sorgente locale contribuisce a ciò che una pubblicazione dell’entità contiene. È lo stesso passaggio che aggrega pin esegue da terminale, e scrive gli stessi byte. entity è obbligatorio ed è un percorso relativo alla radice del workspace che nomina il documento dell’entità, rifiutato nelle stesse tre forme di release. Non viene nominata alcuna Release: una sorgente remota le cui coordinate non contengono template nomina un unico artefatto per ogni Release che usa l’entità, quindi per fissarla non serve nulla di ciò che fornisce una Release, mentre una sorgente remota le cui coordinate provengono da un template viene fissata per singola Release da aggrega/resolveDependencies; una sorgente locale scritta come template contribuisce ogni file nella directory dell’entità, e ciascuno di essi viene fissato qui. dryRun risolve gli input e risponde con il lock che il passaggio scriverebbe come content, senza scrivere nulla accanto all’entità; la cache dei contenuti si riempie comunque. La risposta contiene entity, kind, name e pinnable — false per un tipo che non legge nulla che un lock registri, nel qual caso nulla accanto all’entità è stato toccato e ogni altro campo è assente — e altrimenti il lock che ha scritto, changed (false quando il lock registrava già ogni pin ed è stato lasciato identico byte per byte), removed dove l’entità ora non legge nulla che un lock registri e il suo lock è stato eliminato, e pins, una voce per ogni classe di pin con il numero che il lock ne contiene. Il file dell’entità stesso non viene mai scritto. Questa richiesta scrive accanto all’entità, all’interno del workspace, e raggiunge gli host nominati dalle sorgenti dell’entità — vedi Raggiungere un registry e scrivere.
  • aggrega/cacheStatus — che cosa contengono le cache su disco: una voce per ogni elemento in cache con la sua dimensione e, dove ne ha uno, il suo digest del contenuto, raggruppate per classe. Accetta il workspace e nient’altro. Ogni classe contiene un reach — workspace per la cache degli artefatti sotto la directory di cache di questo workspace, machine per gli store dei moduli compilati, delle descrizioni dei plugin e dei bundle di documentazione condivisi da ogni progetto sulla macchina — e scope nomina direttamente le classi a livello di macchina. Non scrive nulla. Vedi Raggiungere un registry e scrivere per il motivo per cui il reach si trova in una risposta che non cambia nulla.
  • aggrega/cachePrune, aggrega/cacheEvict, aggrega/cacheClear — recuperano spazio dal contenuto in cache. Un prune rimuove ciò a cui nessun lockfile del workspace fa riferimento; un’eviction riduce lo store dei moduli compilati a maxSize, una quantità di byte scritta come la scrive la riga di comando (5GiB, 512MiB o un numero di byte); un clear svuota ogni cache a cui si rivolge questa sessione. Ogni risposta nomina ciò che ha rimosso, con ogni rimozione che riporta il reach della classe da cui proviene, e ciascuna contiene scope. Ogni risposta nomina anche ciò che ha lasciato al suo posto perché un altro processo lo teneva aperto — Windows rifiuta di rimuovere un file aperto, e l’operazione prosegue con il resto invece di fallire: un prune o un’eviction elenca quelle voci in heldOpen, e un clear conta, per ogni cache che ha svuotato, i file che ha lasciato in heldOpenFiles e la loro dimensione in heldOpenBytes. Altrove l’elenco è vuoto e i conteggi sono zero, e un’esecuzione successiva può recuperare ciò che è rimasto. Queste richieste vanno oltre il workspace — vedi Raggiungere un registry e scrivere.
  • aggrega/registryList — i registry che questo workspace è configurato per raggiungere: per ciascuna voce l’host, l’alias facoltativo, se è quello predefinito, la sua postura di attendibilità come campi distinti e se è presente una credenziale per quell’host. Accetta il workspace e nient’altro. Non contatta alcun registry. Lo stato della credenziale riporta solo la presenza — mai la credenziale, mai la sua forma, e mai se il registry la accetterebbe, cosa che richiederebbe un round trip di rete che un elenco non effettua — e viene letto dall’archivio delle credenziali a livello di macchina, cosa che credentialStateIsMachineWide dichiara esplicitamente.
  • aggrega/search — cerca nell’indice locale dei registry configurati. Ogni campo restringe la ricerca e ognuno è facoltativo, quindi un oggetto params vuoto chiede tutto ciò che l’indice contiene. Non contatta alcuna rete: l’indice è lo snapshot offline scritto sotto la directory di cache di questo workspace. La versione riportata è quella che una risoluzione sceglierebbe — una versione il cui ritiro ha una firma considerata attendibile da questo workspace viene esclusa e nominata in retracted — e la risposta contiene la propria provenienza: indexes fornisce l’età dello snapshot di ciascun registry cercato, stale segnala quello che vale la pena aggiornare e missingIndexHosts nomina i registry configurati privi di indice locale, il cui contenuto è quindi assente dalla risposta.
  • aggrega/registryAdd — registra un registry e la sua policy di attendibilità delle firme. host è obbligatorio; tutto il resto definisce la policy o la destinazione di scrittura. keyPath e trustedRoot nominano file: un valore assoluto — un file scelto in una finestra di dialogo, ad esempio — viene letto dove indica; uno relativo nomina un file all’interno del workspace, risolto rispetto alla radice del workspace anziché rispetto alla directory in cui è in esecuzione il daemon, e uno che risale fuori dalla radice o ne esce tramite un link viene rifiutato con l’errore invalid-params prima che venga letto o scritto qualsiasi cosa. Un trustedRoot relativo viene registrato come il file che nomina nel workspace, così la voce nomina quel file in qualunque directory venga eseguita una verifica successiva. fetchTrust vale true per impostazione predefinita quando la chiave è assente, come nella riga di comando, e adotta al primo contatto la policy pubblicizzata dal registry stesso; trust nella risposta dice che cosa è successo — la policy è stata fissata, il registry non ne pubblicizzava nessuna (e, con unreachable accanto, non è stato possibile raggiungerlo affatto), al suo posto è stata fissata la baseline integrata dell’hub ufficiale, oppure non è stato tentato alcun recupero. La registrazione è quella che esegue aggrega registry add: lo stesso recupero con la stessa postura di rete, che scrive la stessa voce byte per byte. In un workspace offline il recupero viene rifiutato prima di qualsiasi connessione, quindi il registry non viene mai interrogato, e un registry diverso dall’hub ufficiale viene rifiutato a meno che la richiesta non fornisca identities o keyPath, che registrano esattamente ciò che è stato inviato e non effettuano alcun recupero: il messaggio dell’errore è la frase che stampa la riga di comando, preceduta dal codice breve della condizione E0310 — così come il messaggio di ogni rifiuto di questa richiesta che nomina una condizione si apre con il suo codice breve — e non viene scritto nulla. L’hub ufficiale viene comunque scritto con la sua baseline integrata, con una risposta che ha trust.baseline true e trust.reason che dice che all’hub non è stata chiesta la sua policy di attendibilità perché il workspace è offline — il motivo con cui si apre l’avviso della riga di comando — e senza notAdvertised, perché all’hub non è mai stato chiesto nulla. Questa richiesta scrive la configurazione globale per impostazione predefinita — vedi Raggiungere un registry e scrivere.
  • aggrega/registryRemove — elimina la voce di un registry, indicato tramite host o alias descrittivo. Un token che non corrisponde a nulla viene rifiutato invece di ricevere una risposta di successo su una configurazione invariata. Questa richiesta scrive la configurazione globale per impostazione predefinita — vedi Raggiungere un registry e scrivere.
  • aggrega/logout — rimuove la credenziale memorizzata per un registry, la stessa rimozione che aggrega logout esegue da terminale. registry è obbligatorio e nomina l’host del registry così come ti sei autenticato presso di esso; qui non c’è alcun alias da risolvere, perché l’archivio delle credenziali è indicizzato per l’indirizzo presso cui un client si autentica anziché per qualcosa che una configurazione nomina, quindi un host che nessun workspace configura può comunque avere una credenziale che puoi rimuovere. Un host per cui l’archivio non contiene alcuna credenziale viene rimosso con successo e nulla viene riscritto — un chiamante che ha chiesto che un host non abbia credenziali ha ottenuto ciò che ha chiesto, quindi questa è una risposta e non un errore, ed è anche ciò che fa il comando da terminale. La risposta contiene registry e scope. Non contiene alcuna parte della credenziale in nessuna forma, e non riporta nulla sul fatto che ce ne fosse una: accertarlo richiederebbe una seconda lettura dell’archivio che nessuno ha chiesto, quindi interroga aggrega/registryList quando la domanda è la presenza. Non contatta alcun registry — rimuovere una credenziale memorizzata è un atto locale, e non viene chiesto se quel registry avrebbe accettato la credenziale. Questa richiesta modifica l’archivio delle credenziali condiviso da ogni progetto sulla macchina — vedi Raggiungere un registry e scrivere.
  • aggrega/registryUpdate — aggiorna l’indice locale ricercabile letto da aggrega/search. Un registry assente aggiorna tutti quelli configurati; nominarne uno aggiorna solo quel registry. upgrade rilegge integralmente ogni repository, senza confrontare nulla con l’indice già scritto; un aggiornamento senza di esso rilegge già tutto ciò che è cambiato. La risposta contiene il numero di record di ciascun host, i repository che non ha potuto leggere — ciascuno con un reason che inizia con il tipo dell’ultimo errore della lettura, dove ce n’è uno — readsRetried, quante delle sue letture il registry ha rifiutato o interrotto strada facendo e sono state richieste di nuovo, ciascuna contata una volta e zero incluso, i marcatori di deprecazione incontrati, l’error di un host che ha fallito — con unreachable accanto dove quel registry non era raggiungibile — e indexRoot, la directory sotto la cache di questo workspace in cui sono stati scritti gli indici. Questa richiesta raggiunge ogni registry che aggiorna — vedi Raggiungere un registry e scrivere.
  • aggrega/publishEntity — impacchetta un’entità del catalogo e la pubblica in un registro. entity è un percorso relativo alla radice del workspace che nomina il documento da pubblicare, rifiutato nelle stesse tre forme in cui lo è release: assente, assoluto o risolto al di fuori della radice. Un’entità Plugin richiede anche plugin, lo stesso tipo di percorso, che nomina l’eseguibile pubblicato all’interno del manifest dell’entità stessa. registry è la destinazione e il suo valore predefinito è quello configurato nel workspace. dryRun calcola il bundle e il digest su cui approderebbe una sua pubblicazione, e non contatta alcun registro. Omettere sign segue la policy del registro di destinazione, ed è ciò che fa la riga di comando quando il suo flag è assente, mentre inviarlo è una scelta del chiamante; nessuna delle due cose allenta il rifiuto, perché una policy del registro o del workspace che richiede una firma rifiuta una pubblicazione non firmata qualunque cosa dica il campo. pinSources: true esegue il passo di pin dell’autore dell’entità sull’entità prima che venga impacchettata, così l’entity.lock che il passo scrive accanto a essa fa parte di ciò che viene pubblicato: è lo stesso passo che esegue aggrega/pin. Viene eseguito prima di qualsiasi rifiuto che giudica il contenuto dell’entità (una policy di firma, la protezione di immutabilità), per cui una pubblicazione rifiutata in quel punto lascia comunque scritto il lock; un rifiuto che riguarda la richiesta stessa, come un workspace offline o l’assenza di una destinazione, arriva prima e non fissa nulla, e lo stesso vale per il rifiuto di un’entità che condivide la propria directory con un’altra entità, in cui il passo non deve scrivere un lock. Se assente, segue l’impostazione pin_sources_at_push del workspace; se inviato, sovrascrive tale impostazione in entrambe le direzioni. Con dryRun il passo riporta il lock che scriverebbe e non scrive nulla. Una pubblicazione che non esegue il passo rifiuta una Recipe o una FeatureRecipe il cui entity.lock non registra alcun pin per un input che legge, o un pin a cui l’input non corrisponde più, prima che venga impacchettato qualcosa (anche con dryRun), nominando aggrega pin, pinSources e pin_sources_at_push; è il rifiuto che aggrega/resolveDependencies solleva sullo stesso lock. La risposta riporta reference, tag, kind, mediaType, la coppia size, il digest pubblicato (con dryRun, il digest su cui approderebbe quella pubblicazione, quello che stampa aggrega push --dry-run), signed, alreadyPublished, dryRun e reach; pin (la stessa risposta che dà aggrega/pin) dove il passo è stato eseguito; e wholeDirectorySource dove la sorgente locale dell’entità è scritta come template, nominando quella sorgente così come è stata scritta. Una sorgente del genere sceglie la propria directory solo quando una Release compila il template, per cui la pubblicazione porta con sé ogni file della directory dell’entità anziché solo i file che l’entità nomina, e questo campo è il modo in cui un chiamante viene a sapere che ciò è avvenuto, anche in un dry run. Riporta inoltre windowsUnusableEntries dove l’archivio portato dalla pubblicazione contiene voci che Windows non può contenere così come sono scritte (un percorso con una parte che ha il nome di un dispositivo, come CON, AUX o NUL, in qualsiasi combinazione di maiuscole e minuscole e con qualunque estensione segua, oppure una parte che termina con un punto o uno spazio), nominandole una per una: prima il nome del file del documento dell’entità, poi i file che porta con sé; è assente dove non ce ne sono, il che include un’entità pubblicata come solo documento. aggrega in esecuzione su Windows si rifiuta di estrarre una voce del genere, quindi un workspace Windows non può usare la versione. Sono le voci per cui aggrega push emette un avviso, e una richiesta che ha chiesto di ricevere aggiornamenti legge le stesse righe di avviso tra l’avanzamento della pubblicazione; nessuno dei due rifiuta nulla, per cui la pubblicazione procede o viene rifiutata esattamente come avverrebbe senza di esse, anche con dryRun. Questo scrive in un registro e raggiunge risorse oltre questa macchina, e con il passo di pin scrive anche accanto all’entità: vedi Raggiungere un registro e scrivere.
  • aggrega/publishArtifact — pubblica un artefatto di dati autonomo, come un bundle di documentazione. file è un percorso relativo alla radice del workspace, soggetto allo stesso contratto, e i suoi byte vengono pubblicati alla lettera: non viene analizzato alcun involucro di entità e non si effettua alcuno smistamento in base al kind. name e tag indicano il nome con cui viene pubblicato, ed entrambi sono obbligatori. mediaType ha come valore predefinito il tipo del bundle di documentazione. La risposta riporta reference, tag, mediaType, la coppia size, il digest pubblicato, alreadyPublished, dryRun e reach. Non firma nulla: un artefatto pubblicato viene firmato in seguito per riferimento con aggrega/signArtifacts, che richiede solo il riferimento riportato da questa risposta. Questo scrive in un registro e raggiunge risorse oltre questa macchina: vedi Raggiungere un registro e scrivere.
  • aggrega/signArtifacts — firma artefatti già pubblicati e allega ciascuna firma. references contiene uno o più indirizzi di registro anziché percorsi, quindi non sono soggetti al contratto relativo al workspace; una lista vuota, o una voce vuota al suo interno, viene rifiutata. Un’unica identità serve l’intero batch e viene risolta prima che venga firmato qualsiasi riferimento, per cui un batch senza alcuna credenziale disponibile viene rifiutato all’inizio anziché a metà. Lo stesso vale per un batch i cui riferimenti richiederebbero credenziali diverse: una richiesta non nomina alcuna chiave, quindi si tratta della configurazione del workspace che nomina una chiave posseduta per il registro di un riferimento e nessuna, o un’altra chiave, per quello di un secondo; non viene firmato nulla e il rifiuto nomina i registri da ciascuna parte, come descrive References signed together need different signing credentials (I riferimenti firmati insieme richiedono credenziali di firma diverse). Firmare un riferimento in cui non è stato pubblicato nulla viene rifiutato anziché allegato al nulla, e un riferimento che porta già una firma verificata dalla policy di attendibilità del suo registro viene lasciato com’è e contato come firmato, come descrive aggrega sign. jobs, facoltativo, indica quanti riferimenti vengono firmati contemporaneamente: se assente, vengono firmati uno dopo l’altro, e un valore inferiore a 1 viene rifiutato con l’errore invalid-params prima che venga letto qualsiasi riferimento. Ogni riferimento viene comunque firmato esattamente come lo sarebbe da solo, come descrive aggrega sign, e sia l’avanzamento riportato dalla richiesta sia la risposta mantengono l’ordine in cui sono stati forniti i riferimenti. La risposta riporta signed, in cui ogni voce nomina un reference e il digest pubblicato a cui si impegna la sua firma, insieme a reach; un batch in cui un qualsiasi riferimento non è riuscito riceve come risposta un errore che li nomina uno per uno, anziché un risultato con una lista più corta. Questo scrive in un registro e raggiunge risorse oltre questa macchina: vedi Raggiungere un registro e scrivere.
  • aggrega/deprecateArtifact — allega un marcatore di deprecazione firmato a un artefatto già pubblicato. Invia un singolo reference con i relativi severity e reason, oppure from che nomina un file di batch relativo alla radice del workspace; inviare entrambi viene rifiutato. I campi di contenuto sono obbligatori anziché richiesti in modo interattivo: nessuno sta osservando questo flusso, quindi una richiesta a cui ne manca uno viene rifiutata indicando cosa inviare. Appartengono soltanto al singolo reference: un file di batch porta il contenuto di ciascun marcatore nelle proprie voci, quindi una severity, un reason, un replacement o un message inviati accanto a from vengono rifiutati come parametro non valido, nominando ciascuno di quelli inviati, anziché essere ignorati. Qui valgono gli stessi input senza chiave accettati dalle due richieste di firma, perché il marcatore viene firmato tramite il proprio digest, e le voci di un file di batch sono vincolate a un’unica credenziale esattamente come lo sono i riferimenti di un batch di firma. La risposta riporta marked, in cui ogni voce nomina il reference ritirato, la sua severity, il timbro issuedOn e il digest del manifest del marcatore stesso (il marcatore è allegato come referrer senza tag dell’artefatto che ritira, quindi nient’altro lo indirizza), insieme a reach. Questo scrive in un registro e raggiunge risorse oltre questa macchina: vedi Raggiungere un registro e scrivere.
  • aggrega/catalogIndex — l’indice delle entità: kind, name, apiVersion, description, labels, file sorgente e origin di ogni entità nel workspace nominato dalla richiesta. Accetta il workspace e, facoltativamente, release: l’insieme è una proprietà di quella radice del workspace e delle directory di catalogo che configura oppure, con release, delle directory che la configurazione assegna a quella Release; vedi Rispondere nei termini di una Release. Copre entrambi i luoghi da cui proviene un’entità (i documenti Aggrega sotto la radice del workspace e le Features contenute nelle directory di catalogo configurate), perché questa è la superficie su cui un client effettua il join quando ha bisogno dei campi descrittivi di un’entità, e un indice che conoscesse solo uno dei due lascerebbe irrisolvibile parte di ogni lista di candidati. Un documento del workspace conta come entità quando dichiara sia un kind: sia un metadata.name e non dichiara alcun apiVersion appartenente al gruppo di un altro progetto, per cui lo YAML che si trova per caso nell’albero (il file di valori di un chart, una configurazione di CI, un manifest Kubernetes renderizzato) viene saltato anziché elencato. Un documento che non dichiara affatto un apiVersion viene riportato: è un documento Aggrega a cui manca un campo, e vederlo elencato è il modo in cui scopri che è lì da correggere. Vedi Come si indirizza un’entità per il significato di origin e di un file vuoto. Non viene letto alcun documento dietro un link che porta fuori dalla radice del workspace: una directory fuori dalla radice non viene esaminata, e un file fuori da essa non viene letto qualunque cosa dichiari, per cui un’entità che il tuo editor mostra sotto un link del genere non viene elencata come propria del workspace, né offerta da aggrega/attachCandidates o aggrega/connectionCandidates, che leggono gli stessi documenti, nemmeno mentre il tuo editor ha quel documento aperto. Ciò vale qualunque cosa dichiari il documento. L’unica eccezione è una Release che la configurazione del tuo workspace nomina (come build.authoring_release o come chiave di workspace.releases, giudicata in base al file a cui porta il link, per cui nominare il link o quel file è equivalente), che viene letta dal file a cui porta il link, elencata nella posizione del link stesso, così come la elenca aggrega/releaseCandidates, e non nominata; un file nominato da una di queste impostazioni che dichiara qualcosa di diverso da una Release non viene elencato, e il suo link viene nominato. Le directory di catalogo configurate sono il modo in cui un workspace legge altre entità conservate altrove, per cui un link a una directory che la configurazione elenca sotto catalog_dirs (per il workspace o per una Release) non viene esaminato come lo sono i documenti propri del workspace, e nemmeno nominato: la configurazione lo ha raggiunto, e le sue Features vengono elencate dal catalogo, come quelle di ogni directory di catalogo configurata. Le Features elencate dalle directory di catalogo non ne includono mai una dietro un link che porta fuori dalla directory entro cui devono restare le letture di una directory di catalogo (il workspace, per una directory di catalogo al suo interno, oppure la directory stessa, per una che la configurazione nomina al di fuori di esso), per cui un’entità che la risposta nomina come situata dietro un link che non ha letto non viene mai elencata anche accanto a quel nome. La risposta nomina ciascuno di questi link in unreadLinkedDirs, per un link a una directory, e in unreadLinkedFiles, per un link il cui nome termina con .yaml o .yml e che porta a un file (relativo alla radice, dove si trova il link, nell’ordine in cui il workspace viene esaminato), così che un client possa spiegarne il motivo. Un link che la ricerca esclude, per il suo nome, per la sua posizione o per un .gitignore, non viene nominato, e in una risposta nei termini di una Release non lo è nemmeno uno sotto una directory di catalogo letta solo da altre Releases. Un link sotto una directory di catalogo esterna al workspace non ha una posizione relativa alla radice in cui essere nominato, e non viene nominato. Entrambi i campi sono sempre presenti, e vuoti quando non esiste alcun link del genere. Dove il file di configurazione del workspace stesso, o l’overlay gestito dalla CI accanto a esso, è a sua volta un link che porta fuori dal workspace, quel file viene nominato in unreadLinkedFiles comunque lo tratti la ricerca, e l’indice è la lettura propria del workspace senza nulla di configurato: non viene letta alcuna directory di catalogo per esso, e un indice nei termini di una Release viene rifiutato; vedi Radice del workspace e Release attiva.
  • aggrega/entityDefinition — ciò a cui si risolve l’entità nominata: il suo kind, il suo name e la sua version, la sua description e il suo publishScope dove li ha, il file in cui è stata dichiarata, l’authoredLength del testo scritto dall’autore che le sta dietro, e la sua definition come documento YAML con l’ereditarietà già applicata. file viene riportato per ogni kind, come un percorso che puoi aprire: relativo alla radice del workspace per un documento al suo interno, assoluto per uno al di fuori, secondo Come si scrive un percorso riportato. È vuoto in un caso: un’entità risolta da un registro non ha alcun documento scritto su questa macchina da nominare. authoredLength risponde a una domanda diversa (quanto testo scritto dall’autore ha conservato la risoluzione), e solo un Aggregate viene servito con del testo di questo tipo, quindi leggi i due separatamente anziché come coppia. name è l’identità di un’entità, scritta nel modo in cui un’entità ne referenzia un’altra, e può portare un suffisso di versione. Questa è l’unica richiesta qui che parte da un nome anziché da un cursore, quindi è quella da porre quando sai già quale entità intendi. release è facoltativo e risolve il nome nei termini di quella Release; vedi Rispondere nei termini di una Release. Un nome che non si risolve in nulla viene rifiutato anziché ricevere come risposta un documento vuoto; vedi Distinguere i due rifiuti per nome. name può invece essere un riferimento di registro, oci://<host>/<repository>:<tag>, oppure @<digest> al posto di :<tag>, e la risposta è allora l’entità pubblicata a quella coordinata, letta dal suo registro, con published che nomina ciò che è stato letto; vedi Chiedere di una coordinata.
  • aggrega/releaseClosure — la chiusura delle dipendenze di una Release: quali entità raggiunge e a quali versioni risolte, in entities, libraries e plugins, insieme alle identità aggregate e manifest a cui si sono risolti i suoi due puntatori, agli eventuali mappingDiagnostics sollevati dalla risoluzione e alle deprecations registrate su ciò che ha raggiunto — nel suo lockfile e nel record di fiducia dei plugin accanto a esso, così un plugin ritirato collegato in un ruolo di verdetto viene nominato come lo è un riferimento fissato ritirato. release è un percorso relativo alla radice del workspace che nomina una Release al suo interno, lo stesso valore che accetta aggrega/irGraph, rifiutato nelle stesse forme, e richiede un lockfile per lo stesso motivo. Non viene renderizzato nulla. Le sue voci non nominano alcuna source: dicono da cosa dipende la Release, non cosa ha fatto un’esecuzione, che è ciò che riporta aggrega/resolveDependencies. Vedi Una chiusura non è il grafo, perché un client che riceve già il grafo non dispone di questo.
  • aggrega/attachCandidates — quali Features possono collegarsi a un nodo: quelle la cui applicabilità dichiarata è soddisfatta dalle label del nodo. Invia esattamente una coordinata. node nomina un documento del workspace tramite il suo metadata.name; graphNode nomina un nodo sul grafo compilato di release, tramite l’id con cui quel grafo lo indicizza; labels porta direttamente un insieme di label e non nomina nulla, per un client che ne possiede già uno. La risposta ripete la coordinata per cui ha risposto (vuota quando non ce n’era alcuna da ripetere), riporta nodeLabels, le coppie di label rispetto a cui è stata valutata la corrispondenza, labelSource, che dice di che tipo di insieme di label si tratta, e ciascun candidato come kind, name, file sorgente e origin che lo indirizzano. Riportare indietro le label è ciò che rende la risposta verificabile di per sé: un client può spiegare perché è stata offerta una Feature senza formarsi una propria idea delle label del nodo, che è il modo in cui la risposta di un client e quella del compilatore divergono. Per un nodo del grafo, le Features offerte sono quelle raggiunte dalla Release di quel nodo. Accanto a graphNode, connection nomina una connessione tracciata dal componente di quel nodo (il suo socket e il suo alias), e la risposta riporta allora anche slots, ciascuno slot dichiarato dal socket di quella connessione con le Features che possono riempirlo, oppure noSlotReason dove non se ne può riempire nessuno. Vedi Cosa ti dice una risposta sui candidati al collegamento.
  • aggrega/connectionCandidates — a cosa può connettersi l’entità nominata. node è il metadata.name di un’entità, la stessa coordinata che aggrega/attachCandidates accetta con quel nome. Vedi Cosa ti dice una risposta sui candidati alla connessione più avanti, perché le due metà della risposta non sono ugualmente complete e la risposta dice quale è quale.
  • aggrega/insertionPoint — dove va, in un documento scritto dall’autore, una nuova voce sotto un contenitore nominato, espresso in modo che un client la applichi senza analizzare il documento da sé. file nomina un documento contenuto nel workspace, relativo alla radice del workspace, assoluto o come indirizzo file://; un documento fuori dalla radice, così come è scritto o tramite un link che porta fuori da essa (al file o a una directory lungo il percorso), viene rifiutato qualunque grafia lo nomini, e che tu ne possieda o meno una copia; container è il percorso strutturale dalla radice del documento al contenitore in cui va la voce, ciascun elemento una chiave di mapping o una posizione di sequenza scritta in decimale. Quel percorso lo fornisci tu: il daemon legge la struttura del documento stesso e non ricava mai dove va qualcosa da come si chiama. Vedi Cosa ti dice una risposta sul punto di inserimento, perché la posizione da sola non basta per applicare la modifica.
  • aggrega/attachmentContainer — in quale documento va il collegamento di una Feature per un nodo, e in quale contenitore al suo interno. graphNode nomina un nodo sul grafo compilato di release, tramite l’id con cui quel grafo lo indicizza, ed entrambi sono obbligatori: l’id di un nodo è una chiave del grafo di una Release e senza di esso non significa nulla. La risposta riporta node, file e container, una lista di segmenti esattamente nella forma che accetta aggrega/insertionPoint, per cui la coppia si compone senza nulla da ricavare nel mezzo. Per un collegamento su una connessione tracciata dal componente del nodo, aggiungi connection con il suo socket, il suo alias e il document (aggregate o release), e la risposta nomina il contenitore features di quella connessione in quel documento. Vedi Cosa ti dice una risposta sul contenitore del collegamento, perché file fa parte della risposta anziché essere qualcosa che conosci già.
  • aggrega/connectionAtPosition — all’interno della voce di quale connessione cade una posizione in un Aggregate o in una Release, con la risposta espressa nei termini in cui le due richieste precedenti accettano una connessione. file nomina il documento nel modo in cui lo nomina aggrega/insertionPoint, e viene letto innanzitutto da ciò che la sessione contiene per esso; position è il punto al suo interno, una line e un character contati da zero nella codifica della sessione; release nomina la Release il cui grafo compilato registra le connessioni, ed è obbligatorio anche per una posizione nell’Aggregate, perché un nodo del grafo e una connessione esistono solo su un grafo compilato. La risposta riporta graphNode e connection (il suo socket, il suo alias e il document in cui è stata letta la posizione) da passare invariati a aggrega/attachCandidates e aggrega/attachmentContainer, oppure noConnectionReason dove lì non è scritta alcuna connessione. Vedi Cosa ti dice una risposta sulla connessione in una posizione.
  • aggrega/editDocument — applica una modifica strutturata e circoscritta a un documento scritto dall’autore, preservando ogni byte che non tocca. È l’altra metà dei due metodi di localizzazione precedenti: quelli dicono dove va una voce e lasciano a te comporla e applicarla, questo ne compone e ne applica una. edit indica quale delle quattro (add-component, attach-feature, wire-edge, set-value), e un valore al di fuori di esse viene rifiutato anziché interpretato; node è il percorso strutturale dalla radice del documento, una lista di segmenti esattamente nella forma che accetta aggrega/insertionPoint; name è la chiave sotto cui viene scritta la voce e value ciò che contiene, il cui significato dipende da edit; socket viene letto per wire-edge e ignorato altrimenti. dryRun fa tutto ciò che fa la richiesta semplice tranne scrivere, rispondendo con il documento modificato come content, per un client che mostra prima il risultato all’autore; con questa opzione non viene creato nulla e written è vuoto. file nomina il documento in modo relativo alla radice del workspace o tramite il suo percorso assoluto, e un documento fuori dalla radice (così come è scritto, o tramite un link che porta fuori da essa, al file o a una directory lungo il percorso) viene rifiutato senza che nulla venga letto o scritto. Questo scrive il documento che nomini, all’interno del workspace: non risolve alcuna dipendenza, non raggiunge alcun registro e non tocca la rete con nessuna delle due modalità di consegna, e la scrittura è subordinata alla validazione del documento composto rispetto allo schema del suo kind. Vedi Cosa ti dice una risposta di modifica del documento, perché il comportamento predefinito è la scrittura e un rifiuto lascia il file identico byte per byte a com’era.
  • aggrega/releaseCandidates — i documenti Release del workspace nominato dalla richiesta, come percorsi assoluti. Accetta il workspace e nient’altro: l’insieme è una proprietà di quella radice del workspace. L’appartenenza è decisa dal kind del documento (il kind: del file è Release) e non dal nome del file, per cui una Release nominata senza un prefisso convenzionale viene offerta, mentre un file che si chiama semplicemente come una Release no. Questo è ciò che il selettore «quale Release?» di un editor dovrebbe elencare, perché è lo stesso insieme da cui sceglie la cascata della Release attiva descritta più avanti. La risposta riporta anche lockfiles, che associa ogni Release elencata (indicizzata esattamente dalla stringa con cui la elenca releases) al percorso assoluto del suo lockfile; è sempre presente, ed è un oggetto vuoto quando il workspace non contiene alcuna Release. Riporta anche unreadLinkedDirs, che nomina (in modo relativo alla radice, dove si trova il link) ogni link che si trova dove l’elenco leggerebbe una directory e porta a una directory fuori dalla radice del workspace: nessuna directory fuori dalla radice viene esaminata, per cui una Release che il tuo editor mostra al suo interno non viene elencata, e questo campo è ciò che permette a un selettore di spiegarne il motivo. Un link a una directory che la configurazione del tuo workspace elenca sotto catalog_dirs non viene nominato: la configurazione l’ha raggiunta come directory di catalogo, non come luogo in cui si conservano le Releases. È sempre presente, e vuoto quando non esiste alcun link del genere. Accanto a esso, unreadLinkedFiles nomina allo stesso modo ogni link il cui nome termina con .yaml o .yml e che porta a un file fuori dalla radice del workspace: nessun file del genere viene letto, qualunque cosa contenga, per cui una Release raggiunta solo tramite uno di questi link non viene elencata, e il passo della cascata relativo alla Release unica non la conta. L’eccezione è un file che la configurazione del tuo workspace nomina come Release (come build.authoring_release o come chiave di workspace.releases, giudicato in base al file a cui porta il link, per cui nominare il link o quel file è equivalente), che viene letto ed elencato nella posizione del link stesso, e non nominato, purché dichiari una Release; uno che dichiara qualcos’altro non viene elencato, e il suo link viene nominato. È sempre presente, e vuoto quando non esiste alcun link del genere. Dove il file di configurazione del workspace stesso, o l’overlay gestito dalla CI accanto a esso, è a sua volta un link che porta fuori dal workspace, quel file viene nominato qui comunque lo tratti la ricerca, e l’elenco viene letto senza nulla di configurato, per cui una Release che la configurazione avrebbe nominato tramite un link non viene elencata; vedi Radice del workspace e Release attiva. Vedi Dove si trova il lockfile di una Release.
  • aggrega/activeRelease — a quale Release punta il workspace nominato dalla richiesta, come percorso assoluto in un campo release, per un client che decide cosa selezionare per impostazione predefinita. Accetta il workspace e nient’altro. Il campo è sempre presente, e un valore vuoto significa che il workspace non punta ad alcuna Release: è una risposta riuscita e non un errore, per cui un client che la aggiorna a ogni riavvio del daemon non è costretto a trattare un workspace ordinario come un fallimento. Quando il valore è vuoto, la risposta riporta anche reason, un riepilogo di una riga di ciò che la cascata ha cercato, e trace, il resoconto passo per passo; entrambi sono omessi quando una Release è stata risolta. Quando una Release è stata risolta, la risposta riporta invece lockfile, il percorso assoluto del lockfile di quella Release, che è omesso quando non ne è stata risolta nessuna. La Release che nomina non deve necessariamente essere una di quelle elencate da aggrega/releaseCandidates (un marcatore può nominare una Release in una directory che quell’elenco esclude, come vendor/, o una nominata senza estensione YAML), per cui questa risposta è il luogo in cui un client legge il lockfile della Release predefinita. Vedi Dove si trova il lockfile di una Release. Chiedila invece di ricavare la risposta da uno degli input della cascata: un input che la cascata non ha finito per usare nomina una Release diversa da quella che ha scelto. La risposta viene calcolata quando la chiedi, per cui chiederla di nuovo dopo aver scritto un marcatore, modificato la configurazione o aggiunto un file di Release riporta la nuova risposta anziché il workspace com’era all’avvio del daemon.
  • aggrega/setActiveRelease — registra una Release come predefinita del workspace nominato dalla richiesta, scrivendo il marcatore .aggrega/active-release di quel workspace, e risponde esattamente come risponde aggrega/activeRelease una volta scritto il marcatore. Accetta il workspace e release: un percorso relativo alla radice del workspace che nomina una Release al suo interno, soggetto allo stesso contratto a cui è soggetto il release di aggrega/irGraph: un percorso assoluto, uno che esce dal workspace e un valore vuoto vengono rifiutati, e così pure uno che porta fuori tramite un link, a meno che la configurazione del tuo workspace non nomini quella Release. Il marcatore è una riga che nomina la Release in modo relativo alla radice, la forma che legge la cascata descritta più avanti. Viene scritto all’interno del workspace e da nessun’altra parte: dove .aggrega, o il marcatore stesso, è un link che porta fuori dal workspace (che il luogo a cui porta esista già o meno), la richiesta viene rifiutata con l’errore invalid-params, il cui messaggio è la frase della condizione stessa preceduta dal suo codice breve, E0320: … (fatal-halts.md §«A path the operation writes leads through a link out of the directory it must stay inside (Un percorso scritto dall’operazione porta, tramite un link, fuori dalla directory entro cui deve restare)»), che nomina il link e dove porta, e non viene scritto nulla; un link che resta all’interno del workspace viene seguito nella scrittura. La risposta nomina ciò su cui si stabilisce la cascata anziché ripetere ciò che hai inviato, e le due cose differiscono dove build.authoring_release nomina una Release, poiché la configurazione ha la precedenza sul marcatore. Registra un valore predefinito in questo modo anziché scrivere il file da te, così che il punto in cui finisce il marcatore sia giudicato secondo la regola a cui è soggetto ogni file che il prodotto scrive nel workspace; vedi Il confine del workspace.
  • aggrega/effectiveConfiguration — la configurazione in vigore per il workspace nominato dalla richiesta, e il livello da cui proviene ciascuna impostazione. Accetta il workspace e nient’altro: la risposta è una proprietà di quel workspace. layers elenca i file di configurazione e gli override d’ambiente che hanno contribuito, a partire da quello con precedenza più bassa; settings riporta ciascuna impostazione attribuita con il suo nome puntato, il suo valore effettivo e la source che l’ha determinata. Una source è scritta esattamente come la voce corrispondente in layers, per cui le due si uniscono direttamente. Vedi Cosa copre la risposta sulla configurazione effettiva per sapere quale livello nomina una source e quali sono i limiti di ciò che significa una riga.
  • aggrega/configInit — inizializza una configurazione funzionante registrando un registro e la sua policy di attendibilità delle firme, così che una macchina nuova possa scaricare e verificare artefatti firmati senza modificare YAML a mano. registry è facoltativo e un valore assente inizializza l’hub ufficiale, lo stesso valore predefinito che usa aggrega config init; il campo host della risposta nomina quello effettivamente usato. global e workspace sono gli override della destinazione di scrittura, e inviarli entrambi viene rifiutato. Si rifiuta di sovrascrivere un file di configurazione esistente, nominando il file: invia force per procedere comunque, il che unisce la voce del registro a ciò che c’è già e preserva le altre impostazioni. dryRun fa tutto ciò che fa la richiesta semplice tranne scrivere, rispondendo con la configurazione inizializzata come content, per un client che mostra il documento all’autore prima che venga salvato; con questa opzione non viene creato nulla e written è false. Il rifiuto per file esistente si applica anche con dryRun, quindi invia force insieme a esso per ricevere come risposta l’unione che produrrebbe una scrittura sovrascrivente. In un workspace offline può essere inizializzato solo l’hub ufficiale: questa richiesta non accetta identità né chiavi, quindi qualsiasi altro registro viene rifiutato esattamente come lo rifiuta aggrega/registryAdd, codice breve e frase compresi, e va invece aggiunto tramite quella richiesta con una policy fornita a mano. La risposta riporta host, scope, trust e written, e existed, true dove il file di configurazione esisteva già (per cui la voce del registro vi viene unita anziché creare un nuovo file) e assente dove il file viene creato. Per impostazione predefinita scrive la configurazione globale: vedi Raggiungere un registro e scrivere.
  • aggrega/configCapture — congela la configurazione effettiva critica per la build nel file di configurazione proprio di questo workspace, così che il workspace venga compilato allo stesso modo senza la configurazione globale della macchina sottostante. Non accetta alcuna destinazione di scrittura: il congelamento esiste per rendere autonomo un workspace, quindi scrive sempre il file di quel workspace. allPlugins amplia l’insieme congelato dai socket che determinano l’output renderizzato (i binding dei provider e i collegamenti di governance di trasformazione delle label) a ogni socket di plugin, aggiungendo i gate di governance di verdetto e di linter e il socket di importazione. La risposta riporta configFile, workspaceRoot, captured, sockets e catalogDirs. Vedi Cosa lascia una scrittura della configurazione, perché la risposta nomina un documento che ora esiste e l’azione successiva di un client è aprirlo.
  • aggrega/skillsInstall — scrive la skill di Aggrega integrata in questo binario nella cartella delle skill di ciascun assistente indicato dalla richiesta, la stessa installazione che aggrega skills install esegue in un terminale. agents elenca gli assistenti per identificatore, gli identificatori che riporta aggrega/skillsList; un identificatore indicato due volte viene installato una sola volta, e dove più assistenti indicati leggono una stessa cartella condivisa la skill vi viene scritta una sola volta. Un’installazione di progetto lo richiede. Una richiesta con global che non ne nomina nessuno installa per gli assistenti trovati su questa macchina, come fa aggrega skills install --global senza --agent — ciascuno la cui cartella di configurazione si trova nella home directory, o il cui comando si trova nel PATH dell’ambiente del daemon — e viene rifiutata senza scrivere nulla dove non ne viene trovato nessuno; non viene chiesto nulla in modo interattivo, e installed nomina gli assistenti per cui ha scritto. Senza global la skill finisce nella cartella di progetto di ciascun assistente all’interno del workspace indicato dalla richiesta, mai nella directory in cui è stato avviato il daemon; con global: true finisce nella cartella per utente di ciascun assistente sotto la home directory indicata dall’ambiente del daemon (HOME, oppure USERPROFILE su Windows). Ogni destinazione viene controllata prima di scrivere qualsiasi cosa, quindi un rifiuto lascia ogni cartella com’era: un identificatore per cui non è nota alcuna cartella delle skill viene rifiutato nominandolo insieme agli identificatori esistenti, e un file in una destinazione che non porta la riga di commento presente in ogni copia scritta della skill viene rifiutato nominandone il percorso. Una copia che porta quella riga — scritta da un’installazione precedente, o presa dal repository pubblicato delle skill — viene sostituita, ed è così che un aggrega più recente aggiorna la skill alla propria versione. Una cartella di progetto raggiunta tramite un link che esce dal workspace viene rifiutata senza scrivere nulla, come ogni scrittura che il daemon esegue in un workspace — vedi Il confine del workspace. La risposta riporta skill, installed — una voce per ogni cartella scritta, nell’ordine in cui sono stati indicati gli assistenti, ciascuna con gli agents che la leggono, la folder assoluta e replaced — e scope. Con global questo scrive cartelle che legge ogni progetto della macchina — vedi Raggiungere un registry e scrivere.
  • aggrega/skillsList — le skill che questo binario include e ogni assistente per cui aggrega/skillsInstall può scriverle, l’elenco che stampa aggrega skills list. Accetta il workspace e nient’altro, e non ne legge nulla. skills riporta per ogni skill name e description; agents riporta per ogni assistente id, name, projectFolder — relativo alla radice di un progetto, che su questa superficie è il workspace indicato da una richiesta — e userFolder, relativo alla home directory, entrambi separati da barre, ordinati per identificatore. Non scrive nulla e non raggiunge nulla.
  • aggrega/pluginAdd — cerca nel registro configurato un plugin di un tipo nominato e lo aggiunge alla configurazione. type e query sono entrambi obbligatori: type è uno tra provider, governance, linter, importer e cli, e query viene confrontato con i nomi dei plugin di quel tipo e deve risolversi esattamente in uno, per cui una query che corrisponde a più plugin viene rifiutata indicando i candidati anziché essere risolta arbitrariamente. capability nomina la capability servita da un binding provider ed è obbligatorio in quel caso; role nomina il ruolo di un collegamento governance (label-transform, ir-verdict o render-verdict) ed è obbligatorio in quel caso; ciascuno viene letto solo per il proprio tipo e rifiutato su qualsiasi altro, perché un campo che silenziosamente non facesse nulla sembrerebbe aver funzionato. acceptCapabilities è obbligatorio per cli e conferma le capability dichiarate da quel plugin: il comando da terminale ottiene questa decisione chiedendola, mentre questa superficie non ha nessuno a cui chiedere, quindi è il chiamante a ottenerla e inviarla. global e workspace sono gli override della destinazione di scrittura, e inviarli entrambi viene rifiutato. dryRun fa tutto ciò che fa la richiesta semplice tranne scrivere, rispondendo con la configurazione risultante come content; non viene creato né modificato nulla e written è false. Il registro viene comunque interrogato e la versione comunque risolta, perché l’identità in quel contenuto è l’identità che una scrittura avrebbe fissato. dryRun viene rifiutato sul tipo cli, anziché ignorato: ciò che registra l’aggiunta di un’estensione di comando è il digest del contenuto dei byte che ha verificato, un record che il compilatore mantiene anziché un contenuto che qualcuno modifica, e l’aggiunta mette in cache quei byte man mano, quindi viene scritta anziché restituita. La versione viene fissata per te: la query si risolve in un plugin, e nella voce viene scritta la versione che la query nomina come <name>:<version> oppure, in mancanza, la versione pubblicata più alta del plugin; una versione nominata che una ritrattazione ritenuta attendibile da questo workspace ha ritirato viene fissata comunque, e la risposta riporta withdrawn: true. Questo raggiunge un registro, e un’aggiunta di tipo cli che non nomina nessuno dei due ambiti scrive la configurazione globale: vedi Raggiungere un registro e scrivere. Vedi Cosa ti dice una modifica di plugin.
  • aggrega/pluginRemove — elimina la voce di un plugin configurato, in modo che non partecipi più. type è lo stesso insieme accettato da un’aggiunta, e query identifica la voce: il nome breve del plugin, il suo riferimento fissato o, per provider, la capability servita dal binding. Entrambi sono obbligatori. global e workspace sono gli stessi override della destinazione di scrittura, rifiutati insieme allo stesso modo. Una query che non corrisponde ad alcuna voce viene rifiutata anziché ricevere come risposta un successo su una configurazione invariata, per cui a un chiamante non viene mai detto che un plugin ha smesso di partecipare quando non è così, e un errore di battitura non rimuove mai un plugin diverso. Non contatta alcun registro: una rimozione opera solo sul testo della configurazione. Una rimozione di tipo cli che non nomina nessuno dei due ambiti scrive la configurazione globale: vedi Raggiungere un registro e scrivere. Vedi Cosa ti dice una modifica di plugin.
  • aggrega/pluginSync — allinea i record gestiti dalla macchina di un’entità Plugin al suo modulo: l’insieme delle funzioni host derivato dagli import del modulo stesso e il mirror dei comandi letto dall’auto-descrizione del modulo. Nessuno dei due record viene scritto a mano, perché entrambi hanno nel modulo la loro fonte di verità. Entrambi i campi sono obbligatori e nessuno dei due ha un valore predefinito (i record sono derivati dal modulo, quindi un allineamento che non ne nomina nessuno non ha nulla a cui allinearsi), ed entrambi sono percorsi relativi alla radice del workspace, rifiutati quando sono assoluti o si risolvono al di fuori di essa, così come sono scritti o tramite un link. Cambiano solo quei due blocchi: ogni altro byte viene mantenuto alla lettera, commenti, righe vuote e stile delle virgolette compresi, e un file che registra già ciò che il modulo implica viene lasciato identico byte per byte e segnalato come invariato. Questo scrive il file dell’entità che nomini, all’interno del workspace, e non contatta alcun registro. Vedi Cosa ti dice una modifica di plugin.
  • aggrega/pluginGenCatalog — genera un’entità Plugin per ogni guest selezionato, unendo i campi del contratto derivati dall’autodescrizione del guest con un overlay per plugin scritto a mano. fromEmbedded e plugin sono le due modalità di selezione e se ne applica esattamente una: ogni guest incluso in questo binario, oppure un modulo al percorso indicato; indicarle entrambe, o nessuna delle due, viene rifiutato anziché risolto. overlay è obbligatorio ed è una directory di overlay con fromEmbedded o un singolo file di overlay con plugin — quando ce ne sono diversi, un overlay viene associato a un guest per identità, e quando ce n’è uno solo non c’è nulla da associare. outputDir è obbligatorio con entrambe le modalità di consegna, e dryRun non ne esonera: un’esecuzione di prova cambia dove va il contenuto, non di quale file è il contenuto, quindi ogni documento restituito indica comunque il percorso a cui è destinato, e quel percorso è composto a partire da questa directory. I tre percorsi non sono valutati allo stesso modo, e la distinzione segue ciò che la generazione fa con ciascuno. plugin e overlay vengono letti, ed entrambi sono file che hai selezionato tu — un modulo finisce nella directory in cui lo compila la sua toolchain, e il suo overlay viene scritto accanto a esso — quindi ciascuno può essere assoluto e viene letto dove si trova effettivamente. In outputDir si scrive, quindi è relativo alla radice del workspace e viene rifiutato se è assoluto o se si risolve al di fuori di essa, così com’è scritto o tramite un link — una directory non ancora creata sotto una directory collegata che porta all’esterno viene rifiutata come quella directory. Rieseguire con input invariati produce entità identiche byte per byte. Questo scrive le entità generate sotto outputDir, all’interno del workspace, a meno che dryRun non le richieda invece come contenuto. Vedi Cosa ti dice una modifica dei plugin.
  • aggrega/getSchema — il JSON Schema per un tipo di entità o di contratto, letto dalla copia compilata nel binario in esecuzione. kind è il token dello schema in minuscolo con trattini — component, aggregate, release, recipe, ir, wasm-provider e così via — ed è facoltativo, perché seleziona quale di due domande stai ponendo. Se indichi un tipo, la risposta contiene kind e schema, lo schema come documento JSON anziché come stringa che ne contiene uno. Se non ne indichi nessuno, la risposta contiene invece kinds ed entityKinds: quali tipi puoi indicare, a due ampiezze. kinds è ogni token che si può chiedere a questo binario, nello stesso ordine in cui li stampa aggrega get-schema --list. entityKinds è l’insieme più ristretto dei tipi di cui un autore scrive un documento, e ogni voce contiene il token kind da rimandare, il valore documentKind che va nel campo kind: del documento stesso e acceptedBy, che indica se la validazione di una singola entità, la pubblicazione e l’ispezione per nome accettano un documento di quel tipo. Vedi Quali tipi puoi offrire a un autore prima di costruire un selettore a partire da uno dei due. La risposta con lo schema e l’enumerazione non vengono mai combinate, quindi dalla risposta si capisce a quale domanda si è risposto. Un token a cui non corrisponde alcuno schema viene rifiutato con l’intero insieme valido nel messaggio, così un refuso si corregge senza una seconda chiamata. Non prende nulla dal workspace, non contatta alcun registry e non scrive nulla, quindi risponde anche in un workspace del tutto vuoto — ed è questo che lo rende utilizzabile per collegare l’associazione degli schemi di un editor al binario che l’editor sta effettivamente pilotando, anziché a qualunque copia degli schemi sia installata altrove.
  • aggrega/scaffoldEntity — un documento iniziale per un tipo di entità: esattamente i campi richiesti dallo schema di quel tipo, con i valori fissi apiVersion e kind già compilati e un segnaposto ovunque serva un valore. kind è obbligatorio ed è il token dello schema in minuscolo con trattini — component, aggregate, release, recipe, manifest, feature e così via; aggrega/getSchema senza kind indica quali token puoi inviare, e un token a cui non corrisponde alcuno schema viene rifiutato con quell’insieme nel messaggio, così un refuso si corregge senza una seconda chiamata. Un client che offre all’autore la scelta di un tipo legge entityKinds di quel metodo, ovvero l’insieme dei tipi di cui si può scrivere un documento. name è facoltativo e inizializza metadata.name per i tipi il cui schema lo richiede. La risposta contiene kind e skeleton. Vedi Cosa ti dà una risposta di scaffold, perché la risposta è un documento da scrivere e non un documento che è stato scritto. Lo scheletro è derivato dallo stesso schema riportato da aggrega/getSchema, quindi i due rispondono da un’unica fonte. Se gli si invia example al posto di kind, il metodo scrive uno degli esempi eseguibili della documentazione in una nuova directory del workspace, come fa aggrega scaffold --example in un terminale; se gli si invia soltanto list: true, risponde con tutti gli esempi esistenti e non scrive nulla. Entrambe le forme richiedono il workspace, quindi una richiesta per l’una o per l’altra lo nomina in workspaceRoot e una che non ne nomina nessuno viene rifiutata. dir nomina la nuova directory relativa alla radice del workspace e per impostazione predefinita è il nome dell’esempio; un valore assoluto, o uno che si risolve fuori dalla radice — così come è scritto o tramite un link — viene rifiutato prima di leggere qualsiasi cosa, e una directory che contiene qualcosa viene rifiutata e lasciata com’è. La risposta a un elenco contiene examples, ciascuno con i suoi name, level e summary; la risposta a una scrittura contiene example, dir, files — ogni file scritto, relativo a dir — next, i comandi che la pagina dell’esempio indica per compilarlo, assente dove non ne indica alcuno, e version, la versione della documentazione da cui è stato letto l’esempio. Campi di due forme inviati insieme — kind con example, list con example o kind, name con example o list, oppure dir senza example — vengono rifiutati prima di leggere qualsiasi cosa, con le stesse parole con cui li rifiuta lo strumento dell’assistente. Una scrittura acquisisce il bundle della documentazione dove la macchina non ne possiede alcuna copia ammessa dal controllo delle firme del workspace stesso, e scrive all’interno del workspace — vedi Raggiungere un registry e scrivere.
  • aggrega/import — trasforma la descrizione di un sorgente esterno in bozze di file di authoring Aggrega, la stessa conversione che aggrega import esegue da terminale. source è obbligatorio e indica il file o la directory da convertire, come percorso assoluto o relativo alla radice del workspace — una descrizione esportata da un altro strumento si trova ovunque tu l’abbia salvata, quindi questa viene letta dove si trova effettivamente anziché solo all’interno del workspace. Una directory viene letta come la legge aggrega import: limitatamente ai suoi file selezionati dai pattern di file dichiarati dall’importer, esclusa la cartella di output della build del workspace dist/, e confinata a sé stessa ovunque si trovi, quindi nessun link al suo interno viene seguito verso l’esterno. outputDir è facoltativo e indica la directory in cui vanno le bozze, e non segue quel contratto: vi si scrive, quindi è un percorso all’interno del workspace, e un valore assoluto, o uno che si risolve fuori dalla radice — così com’è scritto, o tramite un link, compresa una directory non ancora creata sotto di esso — viene rifiutato. Se lo ometti, le bozze vanno sotto la radice del workspace, dove le scrive aggrega import quando non indica alcuna destinazione — anche con dryRun. format indica esplicitamente il formato del sorgente; se lo ometti, il formato viene riconosciuto dalle firme dichiarate dagli importer — sia quelli del catalogo del workspace sia gli importer core del compilatore — e un sorgente che nessuno riconosce, o che riconoscono importer di più di un formato, viene rifiutato chiedendo format anziché tirare a indovinare. target indica una capability del provider, come compose o helm — la parola a cui si lega lo spec.capability di una Recipe — e produce come bozza, accanto alle bozze dell’importer, il Manifest su cui la Release in bozza viene compilata per quel provider, esattamente come fa aggrega import --target: manifest.yaml, che associa ogni tipo di componente e ogni tipo di funzionalità di cui le bozze hanno bisogno — compresi i tipi di un Aggregate del catalogo che quello in bozza compone — alla Recipe o alla ricetta di funzionalità di quella capability che il catalogo del workspace offre per esso, tramite il suo nome qualificato dalla capability e senza versione: quella che c’è o, fra più d’una, quella che porta il nome del tipo. Lo spec.manifest della Release è impostato su di esso; un tipo senza alcuna, o con più d’una e nessuna con quel nome, resta non associato con un rilievo warn che lo nomina, e un’associazione prodotta dall’importer stesso viene mantenuta dove il catalogo la offre per quel tipo e quella capability, e altrimenti scartata con un rilievo warn. Un target a cui non si lega alcuna Recipe del catalogo viene rifiutato prima che l’importer venga eseguito, indicandolo insieme alle capability a cui si legano le Recipes del catalogo, e non viene scritto nulla; se lo ometti, non viene prodotto alcun Manifest — tranne con sync, che produce la bozza per il target indicato dal record dell’importazione precedente. Un importer core che la macchina non possiede ancora viene scaricato dalla prima importazione che ne ha bisogno — vedi Cosa ti dice una risposta di importazione. dryRun fa tutto ciò che fa la richiesta semplice tranne scrivere, rispondendo con le bozze come contenuto, per un client che le mostra prima all’autore; con questa opzione non viene creato nulla e written è vuoto. sync aggiorna rispetto al sorgente ciò che un’importazione precedente ha prodotto in outputDir, modificando solo ciò che l’importazione ha scritto, come fa aggrega import --sync; senza di esso, una richiesta le cui bozze sovrascriverebbero un Aggregate già presente viene rifiutata. La risposta contiene format, outputDir, written, files, drift, diagnostics, decisions e halted. Vedi Cosa ti dice una risposta di importazione, perché un sorgente che l’importer non è riuscito a convertire completamente è una risposta riuscita e non un errore.
  • aggrega/explainError — ciò che il compilatore dichiara sulla condizione indicata da un codice, e le voci pubblicate che insegnano la correzione nell’authoring. code è obbligatorio e accetta uno qualsiasi dei due identificatori di una condizione: il codice breve che una diagnostica riporta in shortCode, o quello descrittivo in code. È l’espansione di un codice che le diagnostiche su questo canale già riportano, ed è la stessa risposta che aggrega explain stampa da terminale. La risposta contiene sempre la condizione — shortCode, code e message — perché questa parte è dichiarata all’interno del binario e non richiede rete; entries contiene la spiegazione passo passo pubblicata, e note indica perché manca, dove manca. Questo acquisisce il bundle della documentazione quando la macchina non ne possiede una copia ammessa dalla verifica delle firme del workspace stesso — vedi Raggiungere un registry e scrivere. Vedi Espandere un codice riportato da una diagnostica.
  • aggrega/invalidate — un segnale di invalidazione della cache proveniente dal file watcher dell’editor.

Notifiche:

  • $/cancelRequest — dal client al server: interrompe la richiesta in corso inviata con quell’id. Il daemon annulla il lavoro di quella richiesta; un’operazione rileva l’annullamento al successivo confine di passo anziché istantaneamente, quindi il lavoro già avviato prosegue per un momento. Annullare un id per cui non è in esecuzione nulla è un’operazione nulla e sicura.
  • $/progress — dal server al client: ciò che un’operazione lunga sta facendo mentre lo fa, sul token su cui la richiesta ha chiesto di ricevere i resoconti. Viene inviato solo per una richiesta che ne riportava uno. Vedi Seguire un’operazione lunga.
  • aggrega/shutdown — avvia uno svuotamento cooperativo: le richieste in corso terminano, le nuove richieste vengono rifiutate, poi il daemon termina.
  • aggrega/publishDiagnostics — un insieme di diagnostiche inviato dal server (usato per gli avvisi di deriva del lockfile e per lo stato all’avvio). Ogni voce contiene un source che indica quale dei livelli diagnostici del daemon l’ha sollevata: aggrega per un rilievo sui documenti scritti, aggrega-build per un avviso sollevato da una build — ogni avviso che ha sollevato, ovvero lo stesso insieme che stampa aggrega build — e aggrega-lint per un rilievo sulle convenzioni di pubblicazione, gli stessi rilievi che stampa aggrega lint. Il campo è sempre presente in ogni voce, così un client può raggrupparle anziché mostrare un unico elenco indistinto, e non deve mai distinguere una sorgente assente da uno dei livelli. Un frame viene inviato per un file solo quando il suo insieme differisce da quello comunicato per ultimo a questo client, quindi una richiesta che ricalcola gli stessi rilievi non invia nulla; il primo frame di un file, e un frame che svuota l’insieme di un file, sono entrambi differenze e vengono sempre inviati.

Chiedere al processo stesso di fermarsi raggiunge il daemon alle stesse condizioni. Un’interruzione da un terminale, o una richiesta di terminazione da un supervisore o da un runtime di container, avvia lo svuotamento avviato da aggrega/shutdown: le richieste in corso terminano, le nuove richieste vengono rifiutate, poi il daemon termina. Una seconda richiesta termina subito il processo. Un client che avvia il daemon può fermarlo in entrambi i modi, e uno che lo ferma tramite il protocollo e uno che gli invia un segnale ottengono lo stesso svuotamento.

Validazione in tempo reale

A ogni aggrega/validate il daemon valida il buffer dell’editor rispetto allo schema del documento e restituisce diagnostiche che puntano alla chiave problematica — lo stesso verdetto che darebbe una build, su contenuto non salvato. Una richiesta che non invia content chiede del file così com’è su disco; un content inviato vuoto è un buffer vuoto, non una richiesta del file. Un file inviato senza il suo contenuto deve essere uno che il workspace contiene e che può essere letto — un file fuori dal workspace, uno raggiunto tramite un link che porta all’esterno o uno che non esiste viene rifiutato con il codice invalid-params. Le entità di catalogo, gli Aggregates, i Manifests e le Releases vengono riconosciuti dai loro apiVersion e kind. I due documenti che non hanno tale intestazione — la configurazione del workspace .aggrega-config.yaml e il lockfile della Release indicata dalla richiesta — vengono riconosciuti invece dal nome del file, così anche una chiave spuria o malformata in uno dei due viene sottolineata in tempo reale. I file che non sono documenti Aggrega — template di chart Helm, file Compose, manifest Kubernetes e i file .lock di altri ecosistemi come Cargo.lock o flake.lock — non ricevono diagnostiche; il daemon non riporta mai nulla sui file estranei.

Un segnaposto ancora dovuto viene indicato alla sua chiave, con ciò che accetta. Un’entità di catalogo di un tipo che aggrega validate verifica come singola entità viene letta anche per i valori obbligatori che lascia come stringa vuota, secondo la lettura applicata da quel comando, quindi il daemon indica ogni segnaposto che il comando indica per gli stessi byte. Ogni segnaposto è una voce: il suo message dice che la chiave è un segnaposto ancora dovuto, il suo suggest dice cosa accetta il valore, e il suo keyPath riporta il percorso puntato della chiave. La voce prende il posto del rilievo dello schema stesso per quel valore vuoto, e ogni altro rilievo sul documento viene riportato come lo riporta la verifica dello schema. Viene indicato anche un segnaposto che lo schema ammette vuoto, sebbene la verifica dello schema non riporti nulla al riguardo — capability e implements di una Recipe o di una FeatureRecipe in bozza sono quelli che incontrerai. Dove la verifica dello schema rifiuta anche il documento, ogni voce riporta il codice di quella verifica, E0215, e dove lo accetta le voci non riportano alcun codice: gli stessi identificatori che il report del comando riporta per quei byte. Una voce viene disegnata alla chiave che contiene il valore vuoto, sulla riga a cui il comando la indica — anche una chiave il cui nome contiene un punto, come l’etichetta component.aggrega.ai/type, dove un rilievo che la verifica dello schema riporta su quella chiave viene disegnato alla chiave che la racchiude — e keyPath indica la chiave per intero. Ciò vale che la richiesta indichi o meno una Release, perché è una domanda a cui il documento risponde da solo, e a un documento che deve ancora un valore non si chiede ancora nulla sulle convenzioni di pubblicazione: quel livello viene azzerato per esso, come avviene per un documento la cui forma è rifiutata dallo schema.

Ogni richiesta indica la Release a cui si riferisce, e il daemon non ne mantiene nessuna propria. I controlli semantici risolvono la chiusura delle dipendenze di quella Release e leggono il lockfile di quella Release per i suoi pin — oppure, per un’entità di catalogo, leggono le directory di catalogo con cui quella Release viene compilata, come descrive il paragrafo successivo — quindi due richieste che indicano due Releases ricevono una risposta sulla Release indicata da ciascuna. Nulla passa dall’una all’altra: non c’è una Release selezionata da cambiare, e cambiare la Release rispetto a cui validi è un valore diverso nella richiesta successiva, non qualcosa che bisogna dire al daemon di dimenticare.

Un’entità di catalogo indicata insieme a una Release viene verificata come singola entità, nei termini di quella Release. Un file che contiene un Component, una Feature, una Recipe, una FeatureRecipe o un Plugin, inviato con una release, riceve la verifica che esegue aggrega validate <path> --release <release>, sul buffer non salvato dell’editor: i suoi riferimenti — il Component che una Recipe implementa, una libreria a cui fa riferimento un pilastro — si risolvono tramite le directory di catalogo che la configurazione del workspace assegna a quella Release, quindi uno stesso file può essere pulito nei termini della Release che viene compilata con esso e fallire nei termini di una Release le cui directory non contengono ciò a cui fa riferimento. È il verdetto che la riga di comando e lo strumento validate di aggrega mcp danno per la stessa entità accanto alla stessa Release e, come il loro, non percorre alcuna chiusura e non legge alcun lockfile. Un rilievo bloccante è una voce di errore con le parole della verifica stessa e con i suoi codici, disegnata sulla chiave che indica nell’entità e, dove non ne indica nessuna, sulla chiave kind: dell’entità, come descrive Cosa contiene una voce diagnostica — a meno che una build non riporti già quell’errore sul file, nel qual caso la voce della build è l’unico report; un avviso che la verifica solleva durante la lettura del catalogo è una voce di avvertimento che la precede; una verifica pulita su directory tutte presenti non restituisce alcuna voce. Un’asserzione fallita — una che chiama fail, nella Recipe o nel Component che essa implementa — qui non è un rilievo bloccante ma una voce di avvertimento, con le parole della verifica e con i suoi codici, chiusa dalla frase A Release must satisfy this assertion before a build of it can pass., e disegnata dove sarebbe il rilievo bloccante: l’asserzione di una Recipe sulla chiave propria di quell’asserzione sotto assertions, quella di un Component sulla chiave kind: della Recipe. Come un rilievo bloccante, cede il passo alla voce di una build che riporta lo stesso errore sul file. La verifica costruisce l’entità attorno a segnaposto e valori predefiniti dello schema anziché ai valori impostati da una Release, quindi non può distinguere un’asserzione che attende una Release da una che è rotta, e lascia il verdetto a una build, che riporta la stessa asserzione come errore (un’asserzione fallita è un avvertimento). Una directory che la configurazione del workspace elenca per la Release e che non è una directory — perché lì non esiste nulla, ad esempio — arresta la verifica: il file riporta un’unica voce di errore al posto del verdetto della verifica, il rifiuto che ogni comando dà per quella directory, che indica la voce, il file di configurazione e la riga che la elenca, e l’impostazione (Da dove vengono lette le entità locali). Una release che non indica alcun file, o che indica una directory, riceve risposta sul file con la frase con cui la riga di comando la rifiuta, anziché essere verificata nei termini del workspace. Ciò che la build di una singola entità non può sostituire viene giudicato come lo giudica la riga di comando, e ciò che la riga di comando mette da parte o non verifica qui non produce alcuna voce — vedi cosa non verifica la correttezza di una singola entità e, per una Recipe il cui template legge un valore fornito solo da un arco della topologia o da una credenziale allegata, correttezza di una singola entità. L’Aggregate della Release stessa, un Manifest, una Release e una libreria non vengono verificati uno alla volta, perché la verifica di singola entità non accetta quei tipi; per essi restano i controlli sulla chiusura descritti sopra. Un buffer che contiene contenuto Workload viene letto come YAML che non è un documento Aggrega, perché quel contenuto è scritto all’interno del campo workload: di una Recipe o di una FeatureRecipe e viene verificato lì, dove si trova; la riga di comando e lo strumento validate, ricevendo un file Workload tramite percorso, ne verificano la forma a sé stante.

Indicare una Release è facoltativo, e la risposta dice quale delle due cose hai chiesto. Se ne indichi una, ottieni tutto quanto descritto sopra. Se non ne indichi nessuna, ottieni i controlli a cui un documento risponde da solo — se viene analizzato, se la sua forma è ammissibile e, per un’entità di catalogo di un tipo validato come singola entità, quali segnaposto deve ancora — senza risolvere alcuna Release, percorrere alcuna chiusura né leggere alcun lockfile; la risposta contiene allora checked: "document". Se indichi una Release, quella chiave è assente, perché quella risposta è il verdetto completo del metodo e non ha nulla da qualificare.

Leggi la chiave anziché dedurre dalle diagnostiche, perché le due risposte possono sembrare identiche. Un documento ben formato validato senza Release risponde con un elenco di diagnostiche vuoto, che è esattamente ciò con cui risponde un verdetto completo pulito, quindi checked è l’unica cosa che separa «non c’è nulla di sbagliato» da «non è stato esaminato nulla che richieda una Release». Dalla stessa regola segue una conseguenza: un lockfile viene riconosciuto dalla sua correlazione con la Release indicata dalla richiesta, quindi una richiesta che non ne indica nessuna non riconosce alcun lockfile e non riporta nulla su di esso.

Un workspace che non contiene alcuna Release riceve una risposta anziché un rifiuto, ed è questo che mantiene utilizzabile lì il resto del daemon. La validazione è ciò che popola la cache di parsing letta da ogni altra operazione sui file, quindi un repository di solo catalogo, uno scaffold con un singolo Aggregate o una directory di prova ottengono comunque hover, completamento, vai alla definizione, riferimenti, implementazioni e diagnostiche in cache. Un rifiuto li toglierebbe tutti, proprio nei workspace in cui un client non ha alcuna Release da indicare.

Cosa contiene una voce diagnostica

Ogni voce si posiziona con line e column, entrambi a base 1 nella codifica delle posizioni negoziata durante l’handshake, e aggiunge end_line ed end_column quando copre un intero token. message è il testo che un client mostra all’utente, severity lo classifica, e source indica quale dei livelli del daemon l’ha sollevata, come descritto sopra.

I livelli rispondono a domande diverse su uno stesso file, quindi una voce di ciascuno può trovarsi sulla stessa riga senza che l’una sia un duplicato dell’altra: una dice che il deployment non è corretto, un’altra che l’entità non è pubblicabile. Un client che le mostrasse come un unico elenco riporterebbe due volte un singolo problema, ed è la lettura di source che le separa.

La posizione di una voce dipende da ciò di cui parla, non da quale livello l’ha sollevata. Un rilievo su qualcosa che l’autore ha scritto è posizionato sulla chiave sotto cui l’ha scritto, così l’editor lo disegna dove va fatta la modifica. Un rilievo sulla forma della topologia distribuita indica un componente e una chiave di consegna anziché una riga — quelle sono coordinate nella topologia distribuita, non nel documento — quindi viene disegnato sulla chiave kind: del documento e indica invece le sue coordinate nel messaggio. Entrambi i tipi raggiungono il livello aggrega-build, perché una build li solleva entrambi. Anche un rifiuto che una build ha sollevato durante il rendering raggiunge quel livello, sul documento a cui il rifiuto stesso punta — un Workload che non soddisfa i suoi controlli sulla chiave workload della sua Recipe, un’asserzione fallita di una Recipe sulla chiave propria di quell’asserzione, una voce che la composizione del grafo rifiuta sulla chiave sotto cui la Release o l’Aggregate l’ha scritta, e ogni rilievo di un rifiuto che ne riunisce diversi sul proprio documento e sulla propria chiave — e, dove non punta ad alcun documento, sulla chiave kind: dell’Aggregate; lo descrive Un rifiuto sollevato durante il rendering. Quindi un client posiziona ogni voce in base ai suoi line e column e non deduce mai una posizione dal livello.

Un rilievo che non indica alcuna chiave presente nel documento viene disegnato sulla chiave che dà il nome al documento. Un rilievo che i controlli propri di un documento sollevano su ciò che esso dice, il rilievo della verifica di singola entità, e un avviso o un rifiuto sollevato da una build vengono ciascuno disegnati sulla chiave che indicano; dove non ne indicano nessuna, o indicano una chiave che il documento non contiene, vengono disegnati sulla chiave kind: del documento, o sul suo metadata.name se non dichiara alcun kind:, e all’inizio del file solo se il documento non dichiara né l’uno né l’altro o non viene analizzato. Un documento si apre spesso con un commento — ogni file di catalogo ha un’intestazione di licenza — e una voce disegnata sulla sua prima riga starebbe su quel commento e sembrerebbe un errore al suo interno, mentre l’identità del documento stesso è una riga scritta dal suo autore. Una voce che riguarda qualcosa di diverso da ciò che il documento dice viene posizionata all’inizio del file: una voce Dependencies: sulle dipendenze della Release, una fase che si è fermata senza indicare nulla nel documento, un lockfile non allineato, un riferimento che un render ha dovuto rifiutare, una Release che non è stata caricata — e così pure una voce aggrega-lint la cui regola non ha calcolato alcuna riga. Dove una posizione viene dichiarata anziché disegnata, un rilievo che non indica alcuna chiave continua a non averne: la risposta di errore di un rifiuto che non indica alcuna chiave riporta solo il documento nel suo data.

Su quale documento viene pubblicata una voce segue dalla stessa regola. Una validazione che indica una Release risponde sull’Aggregate di quella Release, sulla Release stessa, sul documento di ogni modulo che l’Aggregate importa e sul Manifest che la Release indica. Un rilievo posizionato nella Release — il rifiuto di una voce che la Release scrive su una delle connessioni di un componente, del dimensionamento che dà a quella connessione, di un allegato che lì compila o dimensiona, di una connessione che cabla, di una Feature che solo la Release associa a un componente o a un confine, o dell’infra che assegna a un allegato — viene pubblicato quando si valida il documento della Release, sulla chiave della Release che l’ha scritto, e per niente sull’Aggregate. Un rilievo posizionato nel documento stesso di un modulo — il rifiuto di ciò che dichiara uno dei componenti del modulo, di un socket che i suoi allegati cablano, dei suoi valori o dei valori sulle sue stesse connessioni — viene pubblicato quando si valida il documento di quel modulo, sulla chiave che lì l’ha scritto, e per niente sull’Aggregate. Un rilievo sulla tabella di mappatura del Manifest — una voce che mappa un tipo su una Recipe o FeatureRecipe che non lo implementa, una voce il cui pin di versione non è analizzabile, o un tipo mappato la cui catena extends non può essere seguita — viene pubblicato quando si valida quel Manifest, sulla chiave della voce di mappatura a cui si riferisce, e per niente sull’Aggregate; dove il testo aperto del Manifest non scrive quella voce — una voce che eredita tramite il proprio extends, o una che una modifica non salvata ha rimosso — il rilievo viene pubblicato sulla prima riga del Manifest. Ogni altro rilievo sollevato dalla validazione di quella Release viene pubblicato sull’Aggregate, compresi i rilievi a livello di dipendenze che non indicano alcun documento del tuo workspace — un riferimento o un plugin ritirato, un Component o una Feature del catalogo la cui catena extends non si risolve o il cui schema non è valido, un plugin di gate che non corrisponde al registro di attendibilità, un’istanza di componente che nessuna mappatura risolve, una Recipe o FeatureRecipe il cui provider non può eseguire il rendering di un tipo di input che dichiara, e le segnalazioni informative di sovrapposizione dei pilastri dello schema e di restringimento in estensione. Quindi un rilievo su ciò che l’operatore ha scritto compare mentre la Release è aperta, uno su ciò che un modulo dichiara mentre quel modulo è aperto, e uno su una mappatura mentre il Manifest è aperto, qualunque sia la fase della build che l’ha sollevato; un editor che valida ogni documento aperto rispetto alla Release mostra ciascuno lì. Una Release le cui dipendenze non possono essere risolte affatto non solleva nessuno di quei rilievi, e l’impossibilità di risolverle è un’unica voce all’inizio del documento della Release stessa e di ogni altro documento validato rispetto a essa che il daemon riconosce, come descrive Validazione in tempo reale, e che non verifica come singola entità — il suo Aggregate, il suo Manifest, una libreria, un’altra Release, la configurazione del workspace — con il prefisso Dependencies: e con il resoconto della risoluzione stessa su ciò che l’ha fermata. Sul documento della Release stessa la voce è quel resoconto e nient’altro. Su ogni altro documento dice prima che il documento è verificato rispetto a quella Release e indica la Release come la indica una richiesta — Dependencies: this document is checked against the Release <release>, whose dependencies cannot be resolved: seguito dal resoconto — perché nulla in quel documento dice rispetto a quale Release è stato verificato: un editor che verifica ogni documento aperto rispetto all’unica Release selezionata mette la voce su documenti che non hanno nulla a che fare con quella Release, e il nome è ciò che ti dice che la causa è la selezione. Un file che il daemon non riconosce non riporta alcuna voce del genere, qualunque sia la Release indicata con esso.

Una risposta contiene ogni livello presente sul file, per quanto sia avanzata la validazione. La risposta di aggrega/validate è l’intero stato corrente del file: ciò che questa validazione ha trovato, le voci aggrega-build che una build, un’anteprima o una richiesta del grafo hanno pubblicato sul file, e i suoi rilievi sulle convenzioni di pubblicazione, ciascuno sotto il proprio source. Una validazione che si ferma al buffer — uno che non viene analizzato, o un documento il cui involucro è rifiutato dallo schema — risponde allo stesso modo: riporta il proprio rilievo e lascia in piedi ogni voce di build sul file, perché non ha appreso nulla sulla build. Quindi un client può sostituire ciò che conserva per il file, livello per livello, a partire da qualsiasi risposta.

Un errore viene riportato una sola volta. La validazione propria di un documento e una build possono trovare lo stesso errore al suo interno: la verifica di singola entità esegue il rendering di una Recipe di cui anche una build esegue il rendering, la validazione compone il grafo che una build compone, e una Release le cui dipendenze non si risolvono fa fallire entrambe. Finché una build riporta un tale errore su un documento, la validazione di quel documento non lo riporta una seconda volta: una voce aggrega che indica la stessa condizione — lo stesso code — del rifiuto di una build sullo stesso documento, posizionata nello stesso intervallo o in nessuna chiave propria — disegnata dove viene disegnata una voce che non indica alcuna chiave, o all’inizio del file — viene esclusa da ogni risposta e da ogni pubblicazione per quel documento, e il report della build resta da solo. Il report della build è la voce del rifiuto sul livello aggrega-build; oppure, per aggrega/build, aggrega/buildPreview o aggrega/irGraph rifiutati con 1004 perché una dipendenza non si risolve, quella risposta stessa — che nulla pubblica — sul documento indicato dal suo data.file, altrimenti dal suo data.lockfile, altrimenti sulla Release indicata dalla richiesta, e per una Release conta l’ultima di tali risposte. La validazione conserva ciò che ha trovato: quando nessuna build riporta più l’errore — l’esecuzione successiva pubblica il livello senza di esso, la successiva risposta di build, anteprima o grafo per quella Release è qualsiasi altra cosa, o si connette un client a cui non è stata data alcuna risposta 1004 di questo tipo — la voce propria del documento viene riportata di nuovo, e dove non è stata eseguita alcuna build non viene escluso nulla. Una voce aggrega posizionata in una chiave in cui non si trova alcun rifiuto di build resta, anche quando indica la stessa condizione, perché può essere un secondo errore di quel tipo che la build non ha riportato.

code è un codice stabile e confrontabile da una macchina per ciò che la voce riporta, così un client può ramificare in base a esso senza confrontare il testo del messaggio. Una sola chiave contiene il codice, chiunque l’abbia assegnato, e source ti dice quale tipo hai in mano, perché i livelli danno i nomi alle cose a partire da vocabolari diversi.

  • In una voce aggrega — un rilievo sui documenti scritti — il codice è la stringa sotto cui è registrata la condizione, scritta come il pacchetto dichiarante seguito dalla regola in kebab-case. È lo stesso valore che un consumatore Go legge con CodeOf, la cui forma e la cui superficie confrontabile sono descritte nel riferimento sui sentinel degli errori.
  • In una voce aggrega-build — un avviso sollevato da una build — il codice è quello assegnato dal punto che l’ha sollevato, e questo livello riporta avvisi provenienti da due vocabolari diversi perché una build solleva avvisi su due tipi diversi di cose. Un avviso sulla forma della topologia distribuita riporta un codice di classe, come unsupported-field, assegnato ovunque sia stato sollevato, che si tratti di un plugin di rendering o del render stesso; un codice di classe indica una classe di avvisi anziché una condizione registrata, quindi non ha una riga nel riferimento dei sentinel, e il riferimento sugli avvisi descrive la classe unsupported-field e il flag che la silenzia. Un avviso sui documenti scritti — un nome a una modifica di distanza da uno dichiarato, un parametro che nulla legge — riporta la stringa sotto cui è registrata la sua condizione, nella stessa forma di una voce aggrega e con una riga nel riferimento dei sentinel. In ogni caso il codice indica cosa è il rilievo e non chi l’ha trovato, quindi una singola classe ti raggiunge sotto un unico codice per quanti siano i punti che la sollevano, ed è la lettura del codice anziché del livello che ti dice quale dei due hai in mano. Il rifiuto su cui una build si è fermata durante il rendering è l’unica voce qui che non è un avviso, e riporta allo stesso modo la stringa sotto cui è registrata la sua condizione.
  • In una voce aggrega-lint — un rilievo sulle convenzioni di pubblicazione — il codice è l’identità del rilievo: l’identità della regola che l’ha prodotto oppure, per un rilievo che non indica alcuna regola — che un linter tuo può riportare con un codice proprio — quel codice. È l’identificatore che aggrega lint stampa sulla riga del rilievo, dopo il codice breve dove c’è, e il valore che aggrega lint --output json riporta per quello stesso rilievo, come ruleId, o come code per un rilievo che non indica alcuna regola. Un rilievo mantiene un’unica identità tra le varie interfacce, così un client che raggruppa o sopprime una regola nell’editor raggruppa e sopprime la stessa regola nel terminale. Ogni regola dell’insieme di regole del linter di pubblicazione dichiarato da Aggrega è registrata come condizione sotto quell’identità, quindi è elencata nella tabella di tutte le condizioni sotto il codice breve che aggrega lint stampa all’inizio della riga dello stesso rilievo e che aggrega lint --output json vi riporta come shortCode. Una regola di un linter tuo che Aggrega non dichiara non indica alcuna condizione registrata, e nemmeno un rilievo che non indica alcuna regola, anche dove il suo codice riproduce l’identità di una regola dichiarata da Aggrega — quindi nessuno dei due vi è elencato. Le regole sono descritte nel riferimento di aggrega lint.

Qualunque sia il livello, la chiave risponde a un’unica domanda — che cos’è questo, in termini che una macchina può confrontare — quindi un’estensione dell’editor che evidenzia, raggruppa o sopprime una classe di rilievi si basa sul codice, e continua a funzionare quando cambia la formulazione di un messaggio.

Nota quale oggetto contiene cosa: questo è una stringa in una voce diagnostica, distinta dal code numerico nell’involucro di errore JSON-RPC descritto più avanti in Codici di errore. Una risposta contiene l’uno o l’altro, mai entrambi nello stesso punto.

La chiave viene omessa dove nulla di ciò che ha prodotto la voce ha assegnato un codice, e ogni tipo ha questo caso. Un buffer che nessun parser YAML riesce a leggere riporta il testo del parser stesso e nessun codice, perché dietro di esso non c’è alcuna condizione propria di Aggrega; una fase che riporta un errore senza indicare una condizione analogamente non ne ha da riportare; e un avviso a cui chi l’ha sollevato non ha assegnato alcun codice arriva senza. Quindi tratta code come facoltativo, come end_line ed end_column, e ramifica in base a esso solo quando è presente. Un codice è ciò che una diagnostica riporta e mai ciò che ne seleziona una: nessuna richiesta accetta un codice, e riscriverne uno nel tuo codice ti dà una stringa anziché un modo per confrontare.

L’identificatore che un programma confronta e quello che una persona cita

Una condizione ha due identificatori, destinati a due lettori diversi. code è quello visto sopra: qualificato e con trattini, così un programma che ramifica in base a esso si legge per ciò che significa. shortCode è la lettera E seguita da quattro cifre — E0164 — ed è quello che una persona può leggere ad alta voce, digitare in una casella di ricerca o incollare in una issue. Entrambi indicano la stessa condizione e nessuno dei due è l’abbreviazione dell’altro.

Quale usare dipende da chi legge. Confronta su code nella tua estensione; mostra shortCode all’autore. Un’estensione che mostrasse solo code lascerebbe al lettore un identificatore pensato per un programma, e una che confrontasse su shortCode confronterebbe un numero che non dice nulla della condizione. Questa divisione è il motivo per cui viaggiano entrambi anziché uno solo.

codeDescription è dove la condizione è pubblicata, riportato come { "href": … }, che è la struttura propria del protocollo per un riferimento da aprire per saperne di più su una diagnostica. Un editor che conosce il protocollo lo trasforma in un’opzione «scopri di più» senza che gli si debba insegnare nulla su Aggrega, e nessun client ha bisogno di una copia delle spiegazioni. L’indirizzo rimanda all’elenco pubblicato di tutte le condizioni, dove la voce per uno shortCode indica la condizione e prosegue con la spiegazione passo passo della correzione nell’authoring.

Il testo esplicativo non è nella voce, ed è una scelta deliberata. Una diagnostica viene emessa a ogni modifica, quindi una spiegazione che viaggiasse con ciascuna ripubblicherebbe gli stessi paragrafi a ogni battuta di tasto per un lettore che di solito li ha già letti. Un client che vuole il testo lo chiede una volta, con aggrega/explainError più avanti; un client che può seguire un link non ha bisogno né dell’uno né dell’altro.

Entrambe le chiavi sono presenti esattamente quando la voce indica una condizione registrata, e altrimenti sono assenti insieme. A deciderlo è ciò che sta dietro la voce anziché il livello che l’ha pubblicata, quindi leggi le chiavi anziché il livello:

  • Una voce che indica una condizione registrata le contiene tutte e tre. shortCode si risolve, e il riferimento rimanda all’elenco in cui si risolve.
  • Una voce il cui codice indica una classe contiene solo code. La classe di un avviso di render e l’identità di un rilievo sulle convenzioni prodotto da un linter tuo — una regola che Aggrega non dichiara, o il codice riportato da un rilievo che non indica alcuna regola — sono identificatori reali su cui puoi raggruppare e sopprimere, e nessuno dei due è una condizione registrata — quindi non c’è alcun numero da citare e nulla all’indirizzo che li descriva. Un riferimento inviato comunque sarebbe un link che apre una pagina non pertinente al problema del lettore, ed è per questo che non ne viene inviato nessuno. Questa è la forma ordinaria sul livello aggrega-build, sebbene un avviso di build che indica una condizione registrata le contenga tutte e tre come qualsiasi altra. Sul livello aggrega-lint la forma ordinaria è l’insieme completo: una regola dell’insieme di regole del linter di pubblicazione dichiarato da Aggrega è una condizione registrata, quindi il suo rilievo riporta lo stesso shortCode che aggrega lint stampa all’inizio della riga del rilievo, con il riferimento accanto.
  • Una voce che non indica nulla non contiene alcun identificatore.

Quindi i tre casi si distinguono dalle sole chiavi: nessun code significa niente da indicare, un code senza shortCode accanto significa un identificatore che non rimanda oltre, e l’insieme completo significa un identificatore con un posto in cui leggerne. Tratta le due nuove chiavi come facoltative, allo stesso modo di code, e offri al lettore qualcosa da aprire solo dove è arrivato codeDescription.

Espandere un codice riportato da una diagnostica

aggrega/explainError trasforma uno qualsiasi dei due identificatori di una condizione in ciò che il compilatore dichiara su di essa e nelle voci pubblicate che insegnano la correzione nell’authoring. È la stessa espansione che aggrega explain esegue da terminale e che lo strumento explain-error esegue per un assistente, e tutte e tre rispondono da un unico punto, quindi un codice espanso qui e lo stesso codice espanso altrove sono un’unica risposta e non tre che si dà il caso coincidano.

code è obbligatorio e accetta uno qualsiasi dei due identificatori — lo shortCode riportato da una diagnostica, o il code accanto a esso — perché un client che ne possiede uno non ha modo di ottenere l’altro senza chiedere. Un valore vuoto viene rifiutato indicando cosa inviare.

La risposta contiene sempre shortCode, code e message: i due identificatori della condizione e la frase con cui si apre ogni diagnostica che la indica. Questi sono dichiarati all’interno del binario, quindi arrivano senza rete e senza cache, ed è questo che permette di rispondere anche a un workspace che non contiene alcuna documentazione. reference è lo stesso indirizzo riportato dal codeDescription di una diagnostica, per un client che preferisce rimandare il lettore alla documentazione anziché mostrare il testo.

entries contiene la spiegazione passo passo pubblicata, ogni voce come l’heading che la apre e il body sottostante, nell’ordine in cui la documentazione stessa li associa alla condizione. Viene omesso dove non è stato possibile aggiungere la spiegazione, e note dice allora perché: la pagina pubblicata non documenta ancora alcuna voce per questa condizione, oppure questo workspace non può leggere la documentazione — la macchina non ne possiede alcuna copia, o solo una che la verifica delle firme del workspace rifiuta. In entrambi i casi la condizione sopra resta valida — la risposta non è un fallimento, e un client mostra ciò che è arrivato con la nota accanto. entries e note non arrivano mai insieme.

Un codice che nulla risolve viene rifiutato anziché ricevere come risposta una condizione con tutti i campi vuoti, e ogni rifiuto dice di quale caso si tratta: un codice sotto cui non è registrata alcuna condizione, un numero che una volta indicava una condizione e non ne indica mai un’altra, oppure un codice che questo binario non dichiara quando l’elenco pubblicato non è stato affatto leggibile — l’ultimo lascia aperte entrambe le correzioni, poiché un elenco pubblicato per una versione diversa può indicare una condizione che questo binario non dichiara.

La documentazione viene letta dal bundle in cache per il workspace indicato dalla richiesta, acquisito al primo utilizzo quando è assente, ed è l’unica cosa per cui questa richiesta raggiunge un registry — vedi Raggiungere un registry e scrivere. Nel workspace non viene scritto nulla. Nessuna validazione lo attiva: un’espansione avviene perché una richiesta l’ha chiesta, quindi un registry non viene mai raggiunto mentre un documento viene validato o ispezionato.

Convenzioni di pubblicazione, su richiesta e a ogni modifica

Il daemon risponde a due domande diverse su un’entità del catalogo, e sono le domande a cui aggrega validate e aggrega lint rispondono nel terminale: se il deployment è corretto e se l’entità è pubblicabile secondo le convenzioni del catalogo. Una validazione risponde sempre alla prima. Risponde alla seconda solo quando la richiedi.

aggrega/lint la richiede esplicitamente. Invia entity per una singola entità del catalogo, release per ogni entità raggiunta dalla chiusura delle dipendenze di quella Release, oppure nessuno dei due per controllare ogni entità nelle directory di catalogo configurate: sono i tre ambiti che ha il comando. Inviare sia entity sia release nomina due soggetti diversi e viene rifiutato. La risposta contiene checked, il numero di documenti di entità coperti dall’esecuzione, e files, i risultati raggruppati per il documento a cui si riferiscono e ordinati per percorso, con le voci di ciascun file nella forma di diagnostica descritta sopra. halted indica se il verdetto dell’esecuzione stessa rifiuta la pubblicazione.

Non inviare nessuno dei due controlla l’intero catalogo come fa aggrega lint senza argomenti. Un workspace la cui configurazione non indica directory di catalogo di Release proprie viene controllato una volta, sulle proprie directory, e la risposta è quella descritta sopra. Un workspace che nomina delle Releases sotto workspace.releases viene controllato una volta per ciascuna Release al suo interno, sulle directory che quella Release legge, e mai su tutte insieme: così le varianti di catalogo tenute affiancate, una per Release, vengono controllate ciascuna nei termini della Release che le legge. La risposta contiene allora anche passes, una voce per passata: releases, le Releases per cui è stata eseguita, ciascuna relativa alla radice del workspace, con le Releases che leggono le stesse directory che condividono una voce; catalogDirs, le directory che ha letto, scritte come files scrive un percorso, e vuoto per una Release che non ne legge nessuna, il che viene segnalato anziché far fallire le altre; e i conteggi e i files propri di quella passata, che sono ciò che indica per quale Release è stato trovato un risultato. checked, i conteggi e files intorno a essi coprono tutte le passate insieme, così un client che non legge passes legge comunque l’intera esecuzione. Un’esecuzione in cui nessuna passata ha una directory da leggere viene rifiutata anziché ricevere la risposta di un catalogo pulito.

Imposta prePublish insieme a entity per confrontare quell’entità con la sua versione pubblicata in precedenza e classificare rispetto a essa l’incremento di versione proposto. È l’unica modalità qui che raggiunge un registry, e viene eseguita perché la richiesta l’ha nominata: ciò che ammette un’operazione che si rivolge all’esterno è che un chiamante l’abbia richiesta. Ha senso solo con entity, quindi prePublish senza entità viene rifiutato.

aggrega/lint non pubblica nulla nella sessione. Risponde sul soggetto che gli è stato dato, e scrivere i suoi risultati nell’elenco dei problemi dell’editor sostituirebbe ciò che una validazione ha pubblicato per file che la richiesta non ha mai coperto. Nulla viene scritto su disco in nessuna modalità.

serve.lint_on_validate esegue le stesse regole a ogni validazione, ed è disattivata a meno che tu non la attivi. Attivala in .aggrega-config.yaml, nel workspace sulle cui entità vuoi ricevere il parere:

serve:
lint_on_validate: true

Non esiste un flag per questa opzione, perché la domanda a cui risponde riguarda il contenuto stesso di un workspace, e chi si pone quella domanda è la persona che scrive il workspace e non chi ha avviato il daemon. Con l’opzione attiva, una validazione di un’entità del catalogo pubblica anche i risultati sulle convenzioni sotto la sorgente aggrega-lint; con l’opzione disattivata, il valore predefinito, una validazione riporta solo i livelli di correttezza e nessun risultato sulle convenzioni ti raggiunge. Una sessione dell’editor non dice nulla sul fatto che un’entità sia pubblicabile finché non richiedi quel livello.

Tre cose valgono per quel livello, qualunque cosa dica la chiave. Viene eseguita solo la modalità che legge contenuti locali, quindi nessun registry viene consultato, nulla viene scaricato e nulla viene scritto; il confronto pre-pubblicazione si raggiunge inviando aggrega/lint con prePublish, mai con una validazione, perché un controllo eseguito a ogni modifica è esattamente il punto in cui un registry non deve essere raggiunto. Le regole vengono valutate sul buffer trasportato dalla richiesta anziché sul file su disco, quindi un nome che correggi smette di essere segnalato prima che tu salvi. E i risultati sono consultivi: un documento che li produce viene comunque validato, e la sua Release viene comunque risolta e renderizzata, quindi aggiunge un livello e mai un rifiuto.

La chiave controlla quel livello e nient’altro. aggrega/lint risponde a qualunque cosa gli venga chiesta con entrambi i valori, perché un chiamante che lo invia ha richiesto il controllo per nome.

Vengono controllati solo i tipi che vengono pubblicati in un catalogo, perché è di questo che trattano le convenzioni. I documenti che non sono contenuto di catalogo, tra cui un Aggregate e una Release, vengono ignorati, e così anche lo YAML che non è affatto un documento Aggrega. È questo che mantiene una sessione silenziosa sui documenti in cui un autore trascorre la maggior parte del suo tempo.

Come viene scritto un percorso riportato

Quando una risposta nomina un documento che il daemon ha individuato per te, una sola regola decide come viene scritto quel percorso: relativo alla radice del workspace quando il documento si trova al suo interno, e il percorso assoluto quando non vi si trova. Ciò copre il file di un’identità di entità, il file di una definizione di entità e il file con cui è indicizzato ogni gruppo in una risposta di lint. Entrambe le forme sono percorsi che puoi aprire, la prima rispetto alla radice che hai indicato, la seconda così com’è, e nessuna delle due viene mai lasciata vuota a causa del punto in cui si trova il documento.

La seconda metà della regola è ciò di cui ha bisogno una directory di catalogo configurata. Un workspace può puntare a directory di catalogo in qualsiasi punto della macchina, e un documento in una di esse è reale quanto un documento sotto la radice. Il percorso assoluto è ciò che lo nomina, ed è la stessa forma che aggrega lint e una diagnostica bloccante stampano per quel file in un terminale: così un file ha un solo nome, qualunque superficie tu abbia interrogato. Ciò che non ti verrà dato è un percorso che risale oltre la radice, che nominerebbe file diversi a seconda di dove venisse letto.

Quale forma ti è stata consegnata si legge dal valore: tutto ciò che la tua piattaforma legge come percorso assoluto è la seconda forma, e tutto il resto è relativo alla radice del workspace. Non hai bisogno di verificarlo per aprire il file (unire un percorso relativo alla radice e aprirne uno assoluto così com’è funzionano entrambi), ma un client che raggruppa per documento del workspace può distinguere le due forme senza chiedere.

Che cosa questa regola non copre. Un percorso che invii è regolato dal contratto proprio di quella richiesta, indicato con la richiesta sopra e di solito più rigoroso: una destinazione viene rifiutata a meno che non sia relativa alla radice del workspace e si risolva al suo interno, collegamenti inclusi. La notifica aggrega/publishDiagnostics riporta il suo file in forma assoluta in ogni caso, dentro e fuori la radice, perché quel valore è l’identificatore che confronti con i tuoi documenti aperti e non una coordinata nel workspace: il tuo editor lo risolve come percorso del filesystem. aggrega/releaseCandidates e aggrega/activeRelease nominano ogni Release e ogni lockfile con il suo percorso assoluto, come dicono le loro voci sopra. E aggrega/irGraph riporta il grafo compilato così come il compilatore lo ha registrato, trattenendo solo i valori che un autore ha dichiarato sensibili, quindi qualsiasi percorso registrato al suo interno è quello registrato dal compilatore, nella forma fissata dal contratto del grafo stesso, e non uno che questo protocollo ha composto per te.

Quali forme accetta un parametro che invii

È ciò che un percorso nomina, e non quale metodo lo trasporta, a decidere quali forme accetta quel parametro. La voce di ciascuna richiesta sopra indica il contratto per i parametri che accetta; quanto segue è il contrasto tra di esse, e il motivo per cui è un contrasto e non un’incoerenza da memorizzare metodo per metodo.

Un parametro che nomina un documento che hai già può essere scritto in tre modi: relativo alla radice del workspace, assoluto, oppure come l’indirizzo file:// che un client language server invia per un documento aperto. Si tratta del file o dell’uri di aggrega/validate, aggrega/diagnostics, aggrega/invalidate, aggrega/hover, aggrega/completion, aggrega/resolve, aggrega/findReferences, aggrega/findImplementations, aggrega/insertionPoint e aggrega/connectionAtPosition. Tutte e tre nominano un solo documento e ricevono la stessa risposta, perché ciascuna viene ridotta a un’unica forma canonica al confine della richiesta prima che qualcosa la legga: così un documento che hai validato con il suo percorso viene trovato con il suo indirizzo, e viceversa, e la forma che invii non cambia nulla della risposta. Un indirizzo viene letto come il percorso che nomina, con i percent-escape decodificati, quando la sua authority è vuota o localhost; uno che nomina un’altra macchina viene letto come la condivisione di rete di quella macchina su un sistema che apre lì un documento in quel modo, e non nomina nulla che il daemon possa aprire altrove. Anche un indirizzo che contiene una query, un frammento, credenziali o una porta non nomina nulla che il daemon possa aprire. Un valore che non inizia con file://, in qualunque combinazione di maiuscole e minuscole, non viene mai letto come indirizzo, e il rifiuto file-non-validato nomina il valore che hai inviato, qualunque forma avesse. Tra questi, aggrega/insertionPoint e aggrega/connectionAtPosition sono i due che leggono il documento dal disco quando non ne hai una copia, e rispondono solo per un documento all’interno del workspace: uno fuori dalla radice (così come è scritto, o tramite un collegamento che ne esce, verso il file o verso una directory lungo il percorso) viene rifiutato qualunque delle tre forme lo nomini, e un documento dentro la radice riceve risposta in tutte e tre. Gli altri otto non leggono nulla dal disco al percorso che nominano (aggrega/validate prende i byte del documento da content, e gli altri rispondono a partire da ciò che è stato validato), quindi rispondono per un documento ovunque tu lo abbia, dentro il workspace o no, e nessun collegamento che nominano viene seguito per leggere un file. Un parametro che nomina un documento che hai selezionato fuori dal workspace è lo stesso caso per lo stesso motivo: il source di aggrega/import viene letto dove si trova effettivamente, come dice la sua voce. Entrambi sono eccezioni al confine del workspace per classe (un documento che il client tiene aperto e un file scelto da una persona) e Il confine del workspace spiega perché ciascuno lo è.

Un parametro con cui il daemon deve individuare un documento all’interno del workspace accetta un percorso relativo al workspace e nient’altro. release è quello da conoscere (su aggrega/irGraph, e con lo stesso contratto ovunque compaia) e un valore assoluto viene rifiutato con l’errore invalid-params, che enuncia il contratto e poi nomina il difetto specifico. Le richieste che scrivono all’interno del workspace sottopongono le loro destinazioni a quello stesso contratto, come dice la voce di ciascuna. Ogni percorso di questo tipo viene poi giudicato in base a dove porta, con un’unica regola sia che la richiesta lo legga sia che lo scriva (la definizione di interno enunciata da Il confine del workspace) e un percorso che porta all’esterno viene rifiutato con l’errore proprio di quella richiesta, che cita il valore così come lo hai inviato, senza leggere né scrivere nulla: vale allo stesso modo per un collegamento a un file esterno e per un collegamento a una directory lungo il percorso, e per un percorso non ancora creato sotto una directory collegata che porta all’esterno, che viene rifiutato per il collegamento anziché essere scritto, o cercato all’esterno e segnalato come mancante. Ciò copre ogni percorso che una richiesta nomina perché il daemon lo legga (release ovunque compaia, l’entity di aggrega/lint e entity, plugin, file e from delle richieste di pubblicazione), così una richiesta non può leggere tramite un collegamento un file che gli elenchi del workspace stesso escludono, e ogni destinazione: le directory in cui scrivono una generazione, un’importazione e una build, l’entità accanto a cui aggrega/pin scrive il suo lock, il file di entità e il modulo che aggrega/pluginSync legge e riscrive, e il documento che aggrega/editDocument modifica. Una release che nomina una Release indicata dalla configurazione del tuo workspace è l’unica eccezione, come dice la voce di aggrega/irGraph.

I due differiscono perché i difetti differiscono. Un parametro che nomina un documento che hai già lascia una sola domanda, quale documento, quindi ridurre la tua forma a quella canonica non perde nulla, e accettarle tutte non ti costa nulla. Un parametro che seleziona un documento dall’interno del workspace non è in quella posizione: nelle librerie di percorsi che un client usa con ogni probabilità, unire un valore assoluto a una radice produce quel valore assoluto anziché un errore. Quindi un valore riparato in silenzio farebbe leggere al daemon (e segnalare risultati su) un percorso che il workspace non ha mai contenuto, e ti verrebbe parlato di un file che non esiste. La risposta è rifiutare anziché riparare, perché un daemon che riparasse un valore del genere lascerebbe ogni client che ne invia uno convinto che il contratto sia facoltativo.

Come viene indirizzata un’entità

Ogni entità nominata da una risposta viene indirizzata allo stesso modo: kind, name e file. Esegui il join su queste tre chiavi con aggrega/catalogIndex per qualsiasi cosa tu voglia mostrare: è la superficie che porta l’intero insieme descrittivo di un’entità (apiVersion, description e labels), quindi una risposta che deve solo nominare un’entità riporta le tre chiavi di indirizzamento e lascia la descrizione a un unico posto. Una ricerca per nome come aggrega/entityDefinition ripete i pochi campi descrittivi di cui tratta la sua risposta; l’indice resta la superficie con cui fare il join quando vuoi l’insieme.

Dove una risposta può nominare entità provenienti da più di un posto, ogni identità porta origin accanto a queste tre chiavi. aggrega/catalogIndex e aggrega/attachCandidates lo fanno entrambe, perché le loro entità provengono dai documenti del workspace e dalle directory di catalogo configurate. Una risposta che attinge a un solo posto riporta solo le tre chiavi e nessun origin, poiché una chiave con un solo valore possibile non ti dice nulla: ogni entità che una tale risposta nomina è un documento del workspace, e il suo file è un percorso relativo al workspace che puoi aprire. Quindi leggi origin dove è presente anziché richiederlo ovunque; le tre chiavi sono ciò su cui fai il join in entrambi i casi.

origin appartiene a una risposta che elenca entità, dove distinguere le popolazioni è un problema di chi legge. Una risposta per nome come aggrega/entityDefinition non ne porta: nomina l’unica entità a cui il nome si è risolto, quindi non ci sono popolazioni da separare. Il suo punto elenco sopra dice quando il suo file è vuoto; non interpretare quel vuoto attraverso i valori di origin qui sotto, che descrivono un elenco.

origin dice da dove il daemon ha letto l’entità, ed è ciò che rende leggibile file.

  • workspace — un documento Aggrega sotto la radice del workspace. file è il suo percorso relativo a quella radice, che è un percorso che il tuo client può aprire.
  • catalog — un’entità risolta dalle directory di catalogo configurate. file è vuoto in questo elenco, e il name è l’intero indirizzo. È vuoto perché l’elenco riporta ciò che la ricerca nel catalogo ha enumerato, che è un’identità e non un documento, quindi la voce non ha alcun percorso da riportare: non si tratta di un percorso trattenuto per il punto in cui si trova. Chiedi a aggrega/entityDefinition lo stesso nome quando vuoi il documento: quella richiesta risolve l’entità e riporta il suo file secondo la regola sopra, quindi una directory di catalogo fuori dalla radice del workspace vi è nominata con il suo percorso assoluto. name è la coordinata che un Aggregate, una Recipe e la ricerca nel catalogo usano comunque.

Leggi i due valori insieme anziché verificare solo file. Un file vuoto da solo non potrebbe dirti se l’entità non ha un percorso nel workspace o se semplicemente non ne è stato riportato uno; origin risponde direttamente a questo.

Dove una Feature è raggiungibile in entrambi i modi (la radice del workspace è essa stessa una delle directory di catalogo configurate, che è una disposizione comune) viene riportata una sola volta, come documento del workspace, perché è la copia il cui file puoi aprire.

Che cosa ti dice una risposta di attach-candidate

aggrega/attachCandidates risponde a una sola domanda, cioè quali Features ammette questo insieme di etichette, e offre tre modi per dire quale insieme di etichette intendi. Invia esattamente una coordinata; inviarne due, o nessuna, viene rifiutato anziché classificato.

{node} indirizza un documento del workspace tramite il suo metadata.name e non richiede altro. La corrispondenza viene valutata rispetto alle etichette che quel documento dichiara in metadata.labels, e la risposta riporta labelSource: "declared".

{graphNode, release} indirizza un nodo di un grafo compilato. graphNode è l’id con cui il grafo indicizza il nodo: lo stesso id che leggi da aggrega/irGraph, inclusa la forma qualificata che porta un nodo fornito da un sotto-aggregato. release è un percorso relativo alla radice del workspace che nomina la Release di cui costruire il grafo, lo stesso valore che accetta aggrega/irGraph. La corrispondenza viene valutata rispetto alle etichette finalizzate del nodo, e la risposta riporta labelSource: "resolved".

{labels} porta l’insieme di etichette stesso e non indirizza nulla. È la forma sottostante alle altre due: la corrispondenza è funzione di un insieme di etichette e delle Features disponibili, quindi un client che ha già un insieme di etichette non ha nulla da nominare e nulla da attendere. Invia un oggetto JSON di coppie di etichette; la risposta riporta labelSource: "supplied" e un node vuoto, perché questa richiesta non ne ha indirizzato nessuno. Un oggetto vuoto è una coordinata (chiede di un nodo che non porta etichette), mentre omettere del tutto la chiave, o inviare null, non indirizza nulla e viene rifiutato.

Le due coordinate per nome sono separate perché i loro spazi di identificatori si sovrappongono. Un id di nodo del grafo e il metadata.name di un documento possono essere la stessa stringa pur nominando cose diverse, quindi un unico parametro che portasse entrambi sarebbe ambiguo, e un daemon che indovinasse quale spazio intendi a volte risponderebbe con sicurezza per il soggetto sbagliato. Dire quale domanda stai ponendo è ciò che elimina l’ambiguità.

labelSource ti dice fin dove arriva la risposta, e i tre valori non sono intercambiabili. declared è una corrispondenza su ciò che un documento dice di sé, che è ciò che una lettura del sorgente può vedere. resolved è una corrispondenza sulle etichette con cui il nodo finisce effettivamente, che sono quelle rispetto a cui una build valuta l’applicabilità: quindi una risposta resolved è un’affermazione su ciò che una build deciderebbe, e una risposta declared non lo è. supplied dice che il daemon non ha letto alcuna etichetta e ha confrontato ciò che hai inviato; quanto sia solida quella risposta dipende interamente da dove proviene il tuo insieme di etichette.

Ecco perché un client che ha un grafo dovrebbe inviare {labels} anziché un nome. Le etichette finalizzate di un nodo sono le etichette del tipo di componente a cui si risolve, non di un documento che per caso ne condivide l’id, e un attachment label-transform può poi aggiungerne, modificarle o rimuoverle: quindi le etichette che decidono l’applicabilità di un nodo non sono necessariamente quelle dichiarate da un singolo documento. Un client che disegna un grafo ha già quell’insieme da aggrega/irGraph; rimandarlo indietro raggiunge la stessa risposta che dà la coordinata {graphNode, release}, senza ricostruire il grafo per ottenerla. Rimanda un insieme che il daemon stesso ha riportato (quello di un nodo da aggrega/irGraph, quello di un’entità da aggrega/catalogIndex) e la tua idea delle etichette di un nodo non può divergere da quella del daemon, perché l’insieme non ha mai lasciato la sua risposta. Se ne assembli uno tu stesso, stai ponendo una domanda ipotetica, a cui viene data una risposta onesta che non è un’affermazione su alcun nodo contenuto nel workspace.

I candidati provengono dal workspace e dal catalogo. Un workspace che tiene le sue Features in un catalogo anziché nel proprio albero non ha alcuna Feature locale, e i suoi candidati sono interamente origin: "catalog". Per un nodo del grafo, entrambi vengono letti nei termini della Release di quel nodo: le Features di catalogo sono quelle dichiarate dalle directory di catalogo che la configurazione del workspace assegna a quella Release, e i documenti propri del workspace vengono offerti escludendo quelli sotto una directory di catalogo letta solo da altre Releases. Un workspace che tiene una variante di una Feature per Release offre quindi al grafo di ciascuna Release la propria variante e mai quella di un’altra, mentre una Feature scritta accanto ai cataloghi, sotto nessuna directory di catalogo, viene offerta per ogni Release. {node} e {labels} non nominano alcuna Release, quindi attingono a ogni documento del workspace e ai catalog_dirs del workspace stesso. Una Feature che non dichiara alcuna applicabilità è candidata per ogni nodo (una dichiarazione assente non pone alcun requisito), mentre una la cui dichiarazione non può essere letta non è candidata per nessuno, perché trattare un selettore illeggibile come soddisfatto lascerebbe che un errore di battitura allarghi ciò che offri.

Un nome che non si risolve è un errore, non un elenco vuoto. Queste due risposte significano cose diverse: un array candidates vuoto dice che questo nodo non ha nulla che possa collegarsi a esso, e riportare così un nome digitato male presenterebbe un refuso come una risposta definitiva. Il rifiuto nomina lo spazio in cui ha cercato, così sai se cercare un documento del workspace o un nodo del grafo. {labels} non ha questo rischio (non c’è alcun nome da digitare male), quindi un insieme di etichette che nulla ammette torna come risposta riuscita con un array vuoto, e una richiesta che il daemon non riesce a leggere viene comunque rifiutata prima che venga eseguita qualsiasi corrispondenza.

La coordinata del nodo del grafo richiede un lockfile; le altre due no. Costruire un grafo significa risolvere ciò che la Release raggiunge, quindi quel percorso rifiuta con l’errore di lockfile assente quando non ne è stato generato nessuno, nominando il comando da eseguire: la stessa precondizione che ha aggrega/irGraph, per lo stesso motivo. Indirizzare un documento del workspace non costruisce alcun grafo, e fornire un insieme di etichette non costruisce nulla, quindi entrambe rispondono su un workspace che nessuno ha ancora preparato.

Riporta e non crea mai. Il metodo non modifica nulla, non scrive nulla e non crea alcun attachment. Comporre e applicare qualsiasi modifica spetta all’editor, che è dove si trovano il buffer e la cronologia degli annullamenti.

Ciò che risolve dipende dalla coordinata, e le tre non sono uguali. {node} non risolve nulla e non raggiunge alcun registry né la rete: i candidati provengono dal workspace e dalle directory di catalogo, entrambi già su disco. {labels} risolve ancora meno: non cerca nulla, perché non c’è nulla da cercare. {graphNode, release} costruisce il grafo della Release, quindi risolve la chiusura delle dipendenze di quella Release nello stesso modo di aggrega/irGraph: prima dalle directory di catalogo locali e dalla cache degli artefatti, e dal registry configurato per un’entità che nessuna delle due contiene. Tutte e tre rispondono offline per un workspace le cui entità sono tutte locali; solo la coordinata del nodo del grafo può andare a cercare oltre.

Interrogare una connessione

Una connessione che un componente disegna può portare attachment propri, che riempiono gli slot che il suo socket dichiara sul Component consumatore: ad esempio una credenziale che il componente presenta a ciò che la connessione raggiunge. Invia connection accanto a {graphNode, release} per chiedere che cosa può andare lì: socket è il socket di dipendenza attraverso cui è collegata la connessione e alias il nome che porta all’interno di quel socket, entrambi esattamente come li ha scritti l’autore. Una connessione esiste solo su un grafo compilato, quindi connection accanto a node o labels viene rifiutato, così come una connessione che non nomina alcun socket o alcun alias, o una che il nodo non disegna.

La risposta è la risposta per il nodo del grafo più gli slot della connessione. candidates mantiene il suo significato, cioè le Features che possono collegarsi al nodo stesso, e viene aggiunto slots, una voce per ogni slot che il socket dichiara, nell’ordine in cui il Component li dichiara:

  • slot — il nome sotto cui viene scritto, nei features della connessione, un attachment che lo riempie.
  • selector, required, inject, sensitive e description — lo slot esattamente come il Component lo dichiara sul socket, vuoto o false dove non dichiara nulla. selector è il vincolo con cui sono stati ristretti i candidati, così puoi spiegare un candidato, o la sua assenza, dalla sola risposta.
  • candidates — le Features che possono riempire questo slot su questa connessione. Una build sottopone un attachment del genere a due regole, ed entrambe vengono applicate: l’applicabilità dichiarata della Feature rispetto alle etichette finalizzate del nodo, a cui è sottoposto ogni attachment del nodo, e il selector dello slot rispetto alle etichette proprie della Feature. Quindi i candidati di uno slot sono sempre tra quelli del nodo, ristretti dal selettore. Una Feature rispetto alle cui etichette il selettore non può essere valutato non viene offerta, perché una build la rifiuta anziché ammetterla.

Dove nessuno slot può essere riempito, slots è un elenco vuoto e noSlotReason dice perché. Leggi il motivo anziché prendere un elenco vuoto per «nessuna Feature corrisponde»: sarebbe una risposta diversa, ed è il motivo che le distingue:

  • feature-created-connection — la connessione l’ha disegnata una Feature, dal proprio blocco di dipendenze. Un attachment viene scritto solo su una connessione disegnata da un componente o dalla Release, quindi qui non va nulla, qualunque cosa dichiari il socket.
  • ad-hoc-socket — il socket è uno che il Component non dichiara. L’autore lo ha nominato, il che è lecito, e un socket non dichiarato non dichiara alcuno slot.
  • no-slot-declared — il Component dichiara il socket senza alcuno slot.

noSlotReason è assente ovunque esista uno slot, e slots e noSlotReason sono entrambi assenti dalla risposta a una richiesta che non ha nominato alcuna connessione: così una richiesta che non nomina alcuna connessione riceve una risposta senza nessuno dei due campi.

document è accettato e qui non cambia nulla. Gli slot sono quelli del socket e i candidati quelli delle Features, gli stessi in qualunque documento sia scritto un attachment; dove va è la risposta di aggrega/attachmentContainer. Un valore diverso da aggregate o release viene comunque rifiutato, perché un valore accettato e ignorato appare a chi lo invia come un valore rispettato.

Che cosa ti dice una risposta di connection-candidate

aggrega/connectionCandidates risponde a due domande contemporaneamente, e solo una di esse ha una risposta completa. Leggere la risposta come un unico elenco filtrato porta a sbagliare l’altra.

Ogni socket riportato porta targets (i Components locali al workspace le cui etichette dichiarate soddisfano il vincolo di etichette che quel socket dichiara su ciò che può soddisfarlo) più il selector da cui sono stati calcolati quei target, il flag required che il socket dichiara e declaration. targets è sempre un array, vuoto anziché assente, così un socket che nulla soddisfa viene comunque riportato come un socket dichiarato dall’entità.

La metà dei target è completa. L’insieme si decide valutando il vincolo dichiarato del socket rispetto alle etichette dichiarate di un candidato, la stessa valutazione che esegue una build, quindi ciò che offri è ciò che lo stesso vincolo ammette durante una build. Un socket che non dichiara alcun vincolo lascia i suoi target senza vincoli e riporta ogni Component: è il significato che il linguaggio dei vincoli dà a un selettore vuoto, non un errore.

La metà dei socket è aperta, e declaration insieme a adHocSocketsAccepted sono il modo per capirlo. L’autore di un Aggregate è padrone della sua topologia e può collegare un socket che l’entità di catalogo del componente non ha mai dichiarato, quindi i socket che un’entità dichiara sono un utile insieme di partenza e non l’insieme dei nomi di socket leciti. Presentali come suggerimenti, non come le uniche scelte: un menu di scelta che offrisse solo i socket dichiarati direbbe all’autore che la sua libertà è più ristretta di quanto sia.

  • declaration è declared quando l’entità indirizzata elenca il socket nel suo usesSchema, e ad-hoc quando non lo fa. Sono gli stessi due valori che porta un arco nel grafo IR, così un unico vocabolario risponde a «da dove viene questo socket» ovunque incontri la domanda.
  • adHocSocketsAccepted riporta se la superficie dell’entità indirizzata accetta un socket che la sua stessa dichiarazione non elenca. Non è sempre vero: la superficie di dipendenza di un Component ne accetta uno, e la superficie di attachment di una Feature no, perché un attachment partecipa alla topologia che la Feature collegata dichiara anziché crearne una propria. Un socket ad hoc su una superficie che non ne accetta viene riportato senza target, perché nessuna connessione attraverso di esso verrebbe costruita.

Nominare un socket nella richiesta limita la risposta a quel solo socket, ed è l’unico modo per chiedere di un socket che l’entità non dichiara: un socket non dichiarato non compare in alcuna dichiarazione da enumerare. Omettilo per ottenere ogni socket che l’entità dichiara, nell’ordine in cui sono scritti.

Ciò che riporta è una corrispondenza sulle etichette dichiarate. Una build valuta il vincolo di un socket rispetto alle etichette finalizzate del nodo all’altra estremità dell’arco, e quelle sono le etichette del tipo di componente a cui quel nodo si risolve, dopo che qualsiasi attachment label-transform ha detto la sua, non necessariamente le etichette del documento che hai nominato. Quindi una risposta positiva qui non è una promessa su ciò che una build deciderà: è lo stesso limite che aggrega/attachCandidates ha con la sua sorgente di etichette declared.

Riporta e non crea mai. Il metodo non risolve nulla, non raggiunge alcun registry né la rete e non scrive nulla: non crea alcun arco e non propone alcun testo. Comporre e applicare la modifica spetta all’editor, che è dove si trovano il buffer e la cronologia degli annullamenti.

Per le identità di entità in targets (kind, name e file) esegui il join con aggrega/catalogIndex come descritto in Come viene indirizzata un’entità. I campi descrittivi sono riportati lì e deliberatamente non ripetuti qui, così questa risposta non porta una seconda copia che possa disallinearsi. I target sono Components del workspace, quindi ognuno ha un file che puoi aprire e nessuno porta un origin: questa risposta attinge a un unico posto, e il join è sulle tre chiavi.

Che cosa ti dice una risposta di attachment-container

aggrega/attachmentContainer si colloca tra le richieste di candidati sopra e il punto di inserimento sotto. Quelle dicono che cosa può collegarsi a un nodo; questa dice in quale contenitore va un attachment per esso, e in quale documento; la successiva dice in quale punto dei byte di quel documento va il testo.

Chiedi il contenitore anziché comporlo. L’id di un nodo e il percorso del sottosistema che lo racchiude sono entrambi scritti con punti tra le loro parti, e un punto è un carattere lecito in un nome che un autore digita: quindi dall’esterno del documento non c’è modo di distinguere un punto strutturale da uno all’interno di un nome. Un client che assemblasse il percorso da sé produrrebbe qualcosa che si legge correttamente e indirizza una chiave che nessuno ha scritto, e la modifica che ne seguirebbe creerebbe quella chiave anziché essere rifiutata. È il compilatore che ha composto entrambi i percorsi, quindi è il compilatore a scomporli.

L’id di un nodo non porta alcuna traccia del sottosistema che lo racchiude. Un componente scritto all’interno di subsystems.billing.subsystems.payments è indicizzato nel grafo come ledger, esattamente come lo sarebbe un componente di primo livello, quindi nell’id non c’è nulla su cui un client possa lavorare, per quanto accuratamente lo divida.

La risposta è composta da tre campi.

  • node ripete il nodo di cui tratta la risposta, così un client con diverse richieste in sospeso abbina ogni risposta alla sua domanda senza tenere un ordine proprio.
  • file è il documento in cui è stato scritto il nodo, relativo al workspace. Fa parte della risposta anziché essere qualcosa che sai già: un nodo fornito da un modulo importato è stato scritto nel documento proprio di quel modulo con il nome che il modulo gli ha dato, quindi sia il file sia l’ultimo segmento del contenitore differiscono da qualsiasi cosa la richiesta abbia nominato.
  • container è il percorso strutturale dalla radice di quel documento, come elenco di segmenti: ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Ogni livello di un sottosistema che lo racchiude si trova di nuovo sotto la chiave subsystems, che è il modo in cui lo scrive il documento. Un componente che l’autore ha scritto al primo livello nomina invece ["spec", "components", "checkout", "features"], perché l’ambito in cui viene compilato un tale componente non è contenuto in alcun file.

È un elenco di segmenti e mai una stringa unita, ed è proprio questo lo scopo della forma. Un percorso unito dovrebbe essere diviso di nuovo da chi lo riceve, il che reintrodurrebbe l’ambiguità di cui sopra una chiamata più tardi. Passa l’elenco a aggrega/insertionPoint come suo container senza modificarlo.

Legge la struttura e mai il significato. La risposta deriva dal documento in cui è stato scritto il nodo, dall’ambito in cui si trova e dal nome che l’autore ha digitato. Nulla viene ricavato da come si chiama un componente, dal tipo che porta o da ciò che dice un’etichetta.

Riporta e non scrive mai. Il metodo non modifica nulla e non scrive nulla in alcun documento. Non crea alcun attachment, non compone testo e non applica modifiche; non decide che cosa può collegarsi, che è compito di aggrega/attachCandidates.

Una richiesta che nomina un nodo che il grafo non contiene viene rifiutata anziché ricevere risposta. Gli id dei nodi sono le chiavi del grafo stesso (leggili dal grafo restituito da aggrega/irGraph) e un nodo fornito da un modulo importato porta un id qualificato. Viene rifiutato anche un nodo per cui il grafo non registra alcun documento: dove va un attachment è un fatto relativo a un documento, quindi un nodo senza documento non ha risposta, anziché averne una vuota.

Richiede un lockfile, per lo stesso motivo di aggrega/irGraph: nominare il contenitore significa costruire il grafo della Release, e un grafo costruito da byte che nulla garantisce verrebbe riportato esattamente come uno verificato.

Un attachment su una connessione

Invia connection accanto a {graphNode, release} (con il suo socket, il suo alias e il suo document) e la risposta nomina il contenitore features sulla voce propria di quella connessione anziché su quella del nodo. document qui è obbligatorio, perché entrambi i documenti possono contenere un attachment su una connessione disegnata dall’Aggregate: lo sviluppatore lo scrive sulla voce della connessione nell’Aggregate, l’operatore sulla voce per arco della Release che la riguarda.

  • aggregate nomina la voce della connessione nel documento in cui è stato scritto il nodo: ["spec", "components", "gateway", "uses", "models", "gpt", "features"] per un componente di primo livello, con ogni sottosistema che lo racchiude scritto livello per livello come sopra. Una connessione disegnata dalla Release non ha alcuna voce nell’Aggregate, quindi lì viene rifiutata.
  • release nomina la voce per arco sotto la voce propria della Release per il nodo (["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"]), che la Release scriva già o no quella voce per arco. Dove non la scrive, aggrega/insertionPoint riporta in missingContainerKeys le chiavi ancora da scrivere. file è allora il documento della Release. Una Release che non scrive alcuna voce per il nodo viene rifiutata: dove viene collocato il nodo spetta all’operatore scriverlo, e la risposta non lo decide.

Una connessione disegnata da una Feature viene rifiutata in entrambi i documenti, per il motivo che feature-created-connection indica sopra. Il nodo, il socket e l’alias vengono confrontati esattamente come scritti, e una connessione che il nodo non disegna viene rifiutata anziché ricevere come risposta un percorso. Ogni altra proprietà di cui sopra resta invariata: la risposta è un elenco di segmenti, legge la struttura e mai il significato, e non scrive nulla.

Che cosa ti dice una risposta di connection-at-position

aggrega/connectionAtPosition è il passo che precede le due richieste sulle connessioni sopra, per un client che ha una posizione in un documento anziché un nodo su un grafo: ad esempio un cursore sulla voce di una connessione. Risponde a quale connessione è scritta lì, nelle coordinate che quelle richieste accettano, e si ferma.

La risposta è una delle due metà, mai entrambe.

  • graphNode e connection — il nodo il cui componente disegna la connessione, tramite l’id con cui lo indicizza il grafo compilato, e la connessione tramite il suo socket e il suo alias, con document che nomina il documento in cui è stata letta la posizione: aggregate per l’Aggregate o un modulo che importa, release per la Release. Passa graphNode, la stessa release e connection a aggrega/attachCandidates per gli slot che il socket della connessione dichiara, e a aggrega/attachmentContainer per sapere dove va un attachment su di essa; il contenitore che nomina si trova proprio all’interno della voce in cui cadeva la posizione.
  • noConnectionReason — perché non viene riportata alcuna connessione. L’insieme è chiuso:
    • no-connection-entry — la posizione non si trova su alcuna voce in cui viene scritto un attachment. Una connessione scritta come elenco di target (db: [store]) e una disegnata dal blocco di dipendenze proprio di una Feature non hanno una tale voce, quindi anche una posizione su una delle due riceve questa risposta.
    • feature-created-connection — la posizione si trova sulla voce della Release per una connessione disegnata da una Feature, che non porta alcun attachment per il motivo che la risposta sugli slot indica sopra. Una Release scrive una tale voce dove il blocco di dipendenze di una Feature disegna attraverso un socket che anche il Component consumatore dichiara; la voce viene costruita sia che non configuri nulla sia che imposti l’infra per arco della connessione.
    • unknown-connection — la posizione si trova su una voce che la Release scrive per una connessione che il grafo compilato non contiene. Una Release che viene costruita può contenerne una: ad esempio una voce sotto un alias che nulla disegna e che non configura nulla (nessun target, nessun infra, nessun features), o una voce per un componente disattivato da un interruttore active:, le cui connessioni escono dalla build insieme a esso.

Quali voci contano. Nell’Aggregate, ogni connessione che un componente disegna, nella sua voce sotto l’alias della connessione nel documento in cui il componente è stato scritto (per un componente fornito da un modulo importato, il documento proprio di quel modulo). Nella Release, ogni voce per arco che scrive, sia che la voce disegni la propria connessione sia che ne configuri una disegnata dall’Aggregate. Dove si trova ogni voce è ciò che registra il grafo compilato, quindi se una chiave sia una connessione non viene mai dedotto da come si chiama. Un componente disattivato da un interruttore active: non è nel grafo compilato, quindi le sue voci nell’Aggregate rispondono no-connection-entry, mentre la voce della Release per una delle sue connessioni risponde unknown-connection.

Una posizione in qualsiasi punto all’interno di una voce è dentro di essa. La voce va dalla sua chiave alias fino all’ultima riga indentata sotto di essa, quindi una posizione sull’alias, sul suo target o all’interno dei suoi features riceve la risposta per quella connessione, e dove le voci sono annidate vince la più interna. Una posizione sulla chiave propria di un socket, sopra gli alias scritti sotto di essa, non è dentro nessuno di essi, che il socket contenga un alias o più, e lo stesso vale per una posizione nell’indentazione prima di una chiave alias.

Quale documento è quale deriva dalla Release. Il file proprio della Release viene letto per le voci che scrive; ogni altro file viene letto per le voci in cui il grafo registra i componenti come scritti. Un documento da cui il grafo della Release non legge nulla risponde no-connection-entry in ogni posizione.

Riporta e non scrive mai, e legge il documento come fa aggrega/insertionPoint: prima dalla copia della sessione e altrimenti dal disco, all’interno del workspace, con gli stessi rifiuti per un documento che si trova fuori da esso, è illeggibile o non è YAML ben formato. Richiede un lockfile, per il motivo per cui lo richiede aggrega/attachmentContainer, e costruisce il grafo senza renderizzare nulla.

Cosa ti dice una risposta sul punto di inserimento

aggrega/insertionPoint è la controparte delle due richieste di candidati precedenti. Quelle dicono cosa può agganciarsi o connettersi; questa dice dove va il testo corrispondente in un documento specifico. Risponde e si ferma lì.

Tu indichi il contenitore; il daemon lo individua. container è un percorso strutturale dalla radice del documento — ["spec", "components", "web", "features"] — ed è la tua dichiarazione di dove va una voce di questo tipo in un documento di questo tipo. Il daemon non ricava quel percorso dal nome di un’entità, dal tipo che porta o da ciò che sembra significare. Legge i byte scritti dall’autore e riporta quali segmenti del percorso questo documento ha già, le colonne in cui si trovano le sue voci e l’ultima riga raggiunta dal suo blocco più interno. Quindi sapere quale chiave resta compito del chiamante, mentre sapere dove vanno le voci di quella chiave in questo file viene da qui.

Per l’aggancio di una Feature a un nodo di un grafo compilato, il chiamante non deve conoscere quella chiave da solo: chiedi a aggrega/attachmentContainer il documento e il contenitore, e passali entrambi qui invariati.

La risposta è una posizione di larghezza zero più ciò che devi scrivere attorno a essa. file è il documento, relativo al workspace. container ripete il percorso richiesto, così un client con più richieste in sospeso abbina ogni risposta alla sua domanda senza tenere un ordine proprio. position inserisce anziché sostituire: nulla di ciò che è già nel documento viene sovrascritto o spostato.

  • precededByLineBreak — inizia il testo che scrivi con un a capo. La posizione si trova alla fine della riga che la nuova voce segue, che è valida sia che il file termini con un newline sia che no, e non altera alcun byte già scritto. È false solo per un documento che non contiene nulla dopo cui posizionarsi, dove si scrive dall’inizio del file.
  • missingContainerKeys — i segmenti del percorso del contenitore che questo documento non contiene ancora, dal più esterno. Ciascuno va scritto come chiave a sé prima che la voce possa andare dentro quello più interno. È vuoto dove l’intero percorso è già presente.
  • entryIndent — la colonna da cui inizia la prima riga della voce stessa, contata in spazi dall’inizio della riga.
  • indentStep — di quanto è rientrato in più ogni livello di annidamento.
  • indentStepMeasured — se quel passo è stato misurato dall’annidamento di questo stesso documento. Dove è false, il documento non presenta annidamento da misurare e il passo è un valore di ripiego, così un client che preferisce imporre il proprio sa di poterlo fare.
  • entryShape — mapping o sequence, ricavato da ciò che il contenitore contiene già, e unknown dove il contenitore non c’è ancora o non contiene nulla. unknown non è un errore: il documento non ha detto che forma prendono le sue voci, quindi la scelta è tua.

Come applicarla. Scrivi un a capo dove precededByLineBreak è impostato. Poi una riga per ogni voce di missingContainerKeys, dalla più esterna, ciascuna composta dalla chiave seguita dai due punti — la prima rientrata a entryIndent meno indentStep moltiplicato per il numero di chiavi mancanti, e ogni successiva indentStep più in là. Poi la voce stessa, rientrata a entryIndent. Dove missingContainerKeys è vuoto, la voce è l’unica riga che scrivi.

Leggi missingContainerKeys anche quando ti aspetti che il contenitore ci sia. Una posizione applicata senza le chiavi che devono precederla produce un documento che non è più analizzabile, ed è l’unico errore che leggendo questa risposta non si deve dare per escluso.

position conta da zero, a differenza di quella di una diagnostica. Sia line sia character partono da 0, come i valori di posizione in stile LSP che questo protocollo riutilizza, mentre line e column di una voce diagnostica partono da 1, come descritto in Cosa contiene una voce diagnostica. Un client che alimenta una superficie con l’altra converte tra le due.

positionEncoding indica le unità in cui è misurato character, ed è la codifica negoziata durante l’handshake. Viene riportata nella risposta anziché lasciata implicita perché una posizione di cui il chiamante deve indovinare le unità è una posizione che non può applicare: offset misurati in un modo e applicati a un buffer misurato in un altro corrompono il documento al primo carattere fuori da ASCII.

Una richiesta che non indica un punto in cui una voce può andare viene rifiutata anziché ricevere risposta. Ciascuno di questi casi è uno stato della richiesta e non del workspace, quindi torna con il codice invalid-params standard e un nuovo tentativo non cambia nulla finché non cambiano file o container.

  • Il documento non è stato indicato, non è all’interno del workspace, non è stato possibile leggerlo o non è YAML ben formato — un documento senza struttura non ha alcuna posizione da riportare.
  • Il percorso del contenitore non indica nulla: non ha segmenti, oppure uno dei suoi segmenti è vuoto.
  • Il percorso attraversa un valore che il documento contiene come scalare. Non si può aggiungere nulla dentro uno scalare, e sostituirlo sarebbe una riscrittura anziché un inserimento.
  • Il percorso raggiunge una collezione che l’autore ha scritto in stile flow. Aggiungervi una voce riscrive byte già scritti dall’autore anziché aggiungere una riga, il che è una modifica e non una posizione.
  • Il percorso indirizza una sequenza a blocchi con qualcosa che non è uno dei suoi indici. Le voci di una sequenza si indirizzano per posizione, quindi un nome non vi raggiunge nulla e non si può creare alcuna voce che porti quel nome.

Legge il buffer che l’editor tiene aperto, non solo il file su disco. La cache di parsing del daemon viene consultata per prima, così una posizione viene riportata rispetto al contenuto non salvato dove ce n’è, e rispetto al file stesso dove la cache non contiene nulla per esso.

Riporta e non scrive mai. Il metodo non modifica nulla, non risolve nulla, non raggiunge alcun registry né la rete e non scrive nulla in alcun documento. Non compone il testo di una voce e non ne applica alcuna. Comporre e applicare la modifica spetta all’editor, che è dove si trovano il buffer e la cronologia degli annullamenti.

Cosa ti dice una risposta di modifica del documento

aggrega/editDocument è l’altra metà della coppia precedente: quelle dicono dove va una voce e lasciano a te comporla e applicarla; questa ne compone e applica una, e scrive. Restano disponibili entrambe, perché un client con un buffer non salvato e un client che modifica ciò che è su disco vogliono metà diverse — un editor con la propria cronologia degli annullamenti colloca il testo da sé, mentre un client che preferisce che il file venga modificato piuttosto che sentirsi dire dove modificarlo invia questa.

Una chiamata applica una modifica, e l’insieme delle modifiche è chiuso. edit indica quale: add-component aggiunge un’istanza di componente sotto un contenitore di componenti, attach-feature aggancia una Feature a un nodo, wire-edge collega una connessione dentro uno dei socket di dipendenza di un nodo, e set-value imposta un valore su un nodo. Non esiste una modifica che elimini, sostituisca un blocco già scritto, riordini qualcosa o scriva alla lettera byte forniti da te — quindi questo non è uno scrittore di file sotto un nome più ristretto, e un valore al di fuori dei quattro viene rifiutato anziché interpretato. Il rifiuto elenca cosa puoi indicare.

Il nodo si indica come percorso strutturale, esattamente come lo accettano le due richieste precedenti. node è il percorso dalla radice del documento — ["spec", "components", "web"] — e il contenitore in cui va la voce deriva da edit. Per add-component il percorso indica il contenitore dei componenti stesso, perché la voce aggiunta è il nodo. name è la chiave sotto cui viene scritta la voce: il nome dell’istanza, il nome dell’aggancio, l’alias della connessione o la chiave del valore. value è ciò che quella voce contiene, e il suo significato deriva da edit — l’entità richiesta dalla voce, il nodo a cui punta una connessione o lo scalare a cui viene impostato un valore. socket viene letto per wire-edge e ignorato negli altri casi.

Un percorso anziché un nome, per lo stesso motivo per cui lo accetta la richiesta di localizzazione: un nome andrebbe cercato, e un nome presente a due livelli lascerebbe al compilatore decidere quale intendevi. Così un client che sa quale nodo sta modificando lo dice, e un client che non lo sa sa di avere una domanda a cui rispondere prima di modificare qualsiasi cosa.

Ogni byte che la modifica non tocca sopravvive. Il documento viene analizzato solo per individuare il contenitore e la riga in cui termina il suo blocco; la voce viene generata e inserita a livello di riga. Commenti, righe vuote, stile delle virgolette, scalari folded e literal, espressioni di template e la forma del newline finale passano tutti invariati, e il passo di annidamento viene misurato dall’indentazione del documento stesso anziché imposto — così una voce arriva nello stile in cui stai già scrivendo. La stessa richiesta sullo stesso documento produce gli stessi byte, così un client può confrontare due esecuzioni e una revisione legge una modifica come un unico diff.

Il risultato deve essere un documento che avresti potuto digitare, ed è a questo che è subordinata la scrittura. Il documento composto viene validato rispetto allo schema del proprio tipo e raggiunge il disco solo se la validazione passa. Una richiesta che produrrebbe qualcosa che lo schema di authoring rifiuta torna come E0275 — the edit was refused because the resulting document would not be valid, and nothing was written (la modifica è stata rifiutata perché il documento risultante non sarebbe valido, e non è stato scritto nulla) — con la proprietà che lo schema non ammetterebbe e la sua posizione. Il file resta byte per byte com’era, quindi una modifica rifiutata è indistinguibile da una mai tentata e puoi riprovare una richiesta corretta sul documento da cui sei partito. È anche per questo che qui non viene ripetuta alcuna regola: chiedere a un documento Release di contenere un valore da sviluppatore viene rifiutato dallo stesso schema che rifiuterebbe il documento digitato a mano.

Ciò che è ammissibile semanticamente non si decide qui. Se un socket di dipendenza sia uno che il produttore dichiara, o se l’applicabilità di una Feature sia soddisfatta, spetta alla risoluzione eseguita da una build, ciascuna con la propria segnalazione. Quindi puoi indicare una connessione di cui questa richiesta non ha mai sentito parlare, e un Aggregate può definire un socket che la sua entità di catalogo non predichiara; ciò che può essere consumato attraverso un socket resta da dichiarare al produttore. Esegui aggrega/validate indicando una Release, o chiedi il grafo, quando la domanda è quella.

La risposta indica cosa è stato inserito e cosa ha raggiunto il disco, e sono domande diverse. content contiene il documento prodotto dalla modifica con entrambe le modalità di consegna. written indica il file che ha raggiunto il disco, ed è vuoto con dryRun. container è il percorso strutturale del contenitore in cui è finita la voce, così puoi individuare ciò che hai appena aggiunto senza ricavare di nuovo quella regola. createdContainers indica i segmenti che questa modifica ha scritto perché il documento non li conteneva, dal più esterno — vuoto nel caso ordinario in cui l’intero percorso era già presente, e leggerlo è il modo per distinguere una voce aggiunta dentro un blocco esistente da una che ha creato il proprio blocco. file e edit ripetono ciò che hai inviato, così un client con più richieste in sospeso abbina ogni risposta alla sua domanda. written, container e createdContainers sono sempre array, vuoti anziché assenti.

Con dryRun non viene creato nulla. written è vuoto, content contiene il documento che una scrittura avrebbe prodotto, e il file resta intatto — così un editor può presentare il risultato all’autore perché lo salvi, lo modifichi o lo scarti. L’impostazione predefinita è la scrittura, perché il prodotto dell’operazione è un documento modificato e una superficie che ne produce uno lo deve consegnare: una richiesta che non dice nulla sulla consegna modifica il file.

Tutto ciò che fa una scrittura, lo fa anche un dry run. Il documento composto viene validato rispetto allo schema del proprio tipo in entrambi i casi, quindi una modifica che una scrittura rifiuterebbe viene rifiutata anche con dryRun, indicando la stessa proprietà — il che significa che l’errore che ottieni da un dry run è l’errore che ti avrebbe dato la scrittura.

Una voce già presente, che contiene ciò che hai chiesto, è un no-op — il documento torna invariato e non viene scritto nulla. Una voce con quel nome che contiene altro viene rifiutata anziché sostituita, perché sostituire ciò che un autore ha scritto non è una delle quattro modifiche.

Dopo una scrittura il daemon rilegge il documento. Ciò che teneva per quel file viene scartato e la sua vista a livello di workspace viene reimpostata, così la successiva richiesta di validazione, hover, completamento o grafo riceve risposta a partire dai byte prodotti dalla modifica anziché dalla versione sostituita. La modifica stessa legge il file su disco e non il buffer che tieni aperto — a differenza della richiesta di localizzazione precedente, che consulta prima il contenuto non salvato. È voluto: scrivere da un buffer non salvato metterebbe sulla pagina contenuto che l’autore non aveva salvato, con il pretesto di applicare una sola voce. Salva il buffer, poi modifica.

Una richiesta che non indica un punto in cui una voce può andare viene rifiutata anziché ricevere risposta, con il codice invalid-params standard, e un nuovo tentativo non cambia nulla finché la richiesta non cambia. Il documento non è stato indicato, non è all’interno del workspace, non è stato possibile leggerlo, non è YAML ben formato o non dichiara alcun tipo con il cui schema verificare il risultato; edit non è stato indicato o non è uno dei quattro; node non indica nulla, o uno dei suoi segmenti è vuoto; non è stato fornito alcun name; wire-edge non ha indicato alcun socket; a set-value è stato passato un mapping o una sequenza dove va uno scalare; il percorso del nodo raggiunge uno scalare o una sequenza, o una collezione scritta in stile flow, dove aggiungere una riga riscriverebbe byte già presenti sulla pagina; oppure il percorso del nodo non raggiunge nulla nel documento.

Non risolve alcuna dipendenza, non raggiunge alcun registry e non tocca la rete con nessuna delle due modalità di consegna.

Cosa copre la risposta sulla configurazione effettiva

aggrega/effectiveConfiguration risponde a due domande: quale configurazione si applica in questa sessione e quale livello ha deciso ogni impostazione. È la stessa risposta che stampa aggrega config show --origin, calcolata una volta e riportata su entrambe le superfici, così le due non possono essere in disaccordo sulla provenienza di un’impostazione.

Un source ha una di quattro forme. Il percorso assoluto di un file di configurazione — incluso il file globale letto da un daemon avviato come aggrega --config <file> serve, indicato con il percorso che gli è stato dato; una variabile d’ambiente dietro un prefisso env:, come env:AGGREGA_SIGNING_REQUIRED; un flag globale digitato sulla riga di comando che ha avviato il daemon, indicato come il flag, come --offline per un daemon avviato come aggrega --offline serve; oppure (built-in defaults) per un’impostazione che nessun livello imposta. Le prime tre compaiono alla lettera in layers. I valori predefiniti no, perché i valori predefiniti non sono un livello che ha contribuito — sono ciò che si applica dove nessun livello si è espresso.

Un’impostazione è attribuita al livello con la precedenza più alta che la imposta, qualunque valore scriva quel livello. Un file di configurazione che scrive il valore predefinito integrato, o che ribadisce un valore già impostato da un file sottostante, è il file indicato: è quello che mantiene il valore. Un file imposta un’impostazione contenendone la chiave, incluso il compagno _append di una lista, e una variabile d’ambiente essendo esportata con un valore non vuoto. Il file di configurazione di proprietà della tua pipeline non viene mai indicato per una chiave che ignora. aggrega config show --origin riporta secondo la stessa regola.

Ogni impostazione dichiarata dallo schema di configurazione è contabilizzata, anche se non ognuna con una riga propria. Il compagno additivo _append di una lista è riportato sulla riga della lista a cui aggiunge, così un livello che contribuisce solo tramite il compagno è indicato sulla riga di quella lista e il compagno non ha una riga. Un’impostazione dentro le voci di una lista — la politica di fiducia di un registry, gli input dell’aggancio di un plugin — è coperta dalla riga di quella lista.

Altri due limiti, ognuno dei quali rende una risposta più grossolana di quanto sembri.

  • Un’impostazione di tipo lista o mappa è attribuita nel suo insieme, al livello con la precedenza più alta che la imposta. L’attribuzione per singola voce non viene tracciata, quindi una lista composta da due livelli riporta solo quello con precedenza più alta, e una voce fornita da un livello inferiore non è distinguibile da una scritta dal livello superiore.
  • Il requisito di firma è attribuito al primo livello che lo ha attivato, non all’ultimo che lo ha menzionato. Quell’impostazione si compone in modo che qualsiasi livello che la attiva prevalga e nessun livello successivo possa disattivarla, quindi il primo livello ad attivarla è quello che ha reso il valore effettivo quello che è. Un livello che scrive required: false non attiva nulla, quindi dove ogni livello che la menziona scrive false l’impostazione riporta (built-in defaults).

Ogni valore riportato è la risoluzione effettuata quando quel workspace è stato indicato per la prima volta. Modificare un file di configurazione non cambia un valore qui; riavviare il daemon sì. È voluto — i valori sono la configurazione con cui riceve risposta ogni altra richiesta su quel workspace, ed è questo che li rende confrontabili con la radice e il livello di configurazione che l’handshake ha riportato per esso. Un client che mostra la configurazione accanto a un file che l’utente sta modificando dovrebbe dire quale delle due cose sta mostrando.

L’attribuzione dei livelli viene calcolata quando la chiedi, sui file così come sono. Quindi un file di configurazione modificato in seguito può spostare un source mentre il valore accanto resta come era stato risolto. Le due metà rispondono a domande diverse — cosa è in vigore e quale livello lo ha deciso — e solo la prima è fissa. Riavvia il daemon per riallinearle.

Riporta e non scrive mai. Il metodo non cambia alcuna configurazione, non crea alcun file e non risolve nulla da un registry o dalla rete.

Il contenuto dei file di un singolo livello non viene servito qui. La riga di comando può stampare alla lettera i byte di un livello, con commenti e formattazione preservati; questo metodo riporta la risoluzione anziché i byte. Un client che vuole il testo di un livello ha il percorso in layers e può aprirlo.

Cosa lascia dietro di sé una scrittura di configurazione

aggrega/configInit e aggrega/configCapture producono entrambi un documento di configurazione, ed entrambi lo scrivono. La risposta indica il file; aprirlo è la tua azione successiva, non un sostituto della scrittura. Nessuno dei due ti consegna contenuto da collocare tu, a meno che tu non lo chieda esplicitamente, perché una funzionalità il cui prodotto è un documento mai scritto è una funzionalità diversa che porta lo stesso nome.

I due differiscono per la portata, e ogni risposta dice quale. Leggila prima di mostrare il risultato.

  • L’inizializzazione scrive, per impostazione predefinita, la configurazione condivisa tra tutti i workspace della macchina. Un registry e le identità di cui ti fidi su di esso sono di solito gli stessi ovunque tu lavori, quindi è lì che va la voce, a meno che la richiesta non invii workspace: true. scope contiene il configFile che è stato scritto e machineWide, che dice se è quello condiviso — ricavato dal file a cui si è risolta la scrittura anziché da ciò che la richiesta ha chiesto, così una risposta non può descrivere una modifica a livello di macchina come locale.
  • Il congelamento non va mai oltre il workspace. Non accetta alcuna destinazione di scrittura né alcuna sostituzione: il suo unico scopo è rendere un progetto autosufficiente, quindi scrive sempre il .aggrega-config.yaml di quel progetto. Per questo la sua risposta contiene configFile e workspaceRoot e non dichiara alcuno scope — non c’è alcuna portata da indicare.

L’inizializzazione rifiuta anziché sovrascrivere. Un file di configurazione che esiste già resta intatto e il rifiuto lo indica, perché l’inizializzazione è per una configurazione che non esiste ancora, mentre la scrittura condivisa a cui delega unisce per progettazione. Invia force per scrivere comunque; la voce del registry viene unita a ciò che è già presente e le altre impostazioni sono preservate. Una richiesta rifiutata non cambia assolutamente nulla.

trust dice cosa ha fatto la politica pubblicizzata dal registry, come esiti distinti anziché come testo. pinned significa che il registry ha pubblicizzato una politica e questa è stata adottata, con identities che conta le identità. notAdvertised significa che il registry è stato interrogato e non ne ha pubblicizzata alcuna, il che non è un errore — l’inizializzazione prosegue, e reason dice cosa ha fatto l’endpoint. Anche un registry che non è stato possibile raggiungere viene riportato così, poiché non è tornata alcuna politica e l’inizializzazione prosegue allo stesso modo, e porta accanto unreachable dove l’errore stesso mostra che il registry non è mai stato raggiunto: il suo nome non è stato risolto, una connessione verso di esso è stata rifiutata o non è stato possibile aprirla, oppure non è stato possibile stabilire una connessione sicura verso di esso. Un registry che ha risposto — con un not-found o con uno stato di errore — non porta mai unreachable, quindi leggi quella chiave anziché le parole di reason per distinguere un registry che non pubblica alcuna politica da uno che non è mai stato interrogato. baseline significa che è stata fissata la baseline integrata dell’hub ufficiale perché non è stata adottata alcuna politica pubblicizzata, con reason che dice perché; la voce porta una politica, quindi non c’è nulla da fissare a mano. Le due chiavi rispondono a domande diverse, quindi un hub che è stato interrogato e non ha pubblicizzato nulla porta entrambe, e un hub in un workspace offline — mai interrogato — porta solo baseline, con reason che dice che il workspace è offline. Qualsiasi altro registry che non pubblicizza nulla porta solo notAdvertised, viene inizializzato senza politica, e il consiglio che segue è fissare le identità a mano; offline viene rifiutato anziché ricevere risposta. skipped significa che non è stato tentato alcun recupero. Un client che trattasse come errore qualunque cosa diversa da pinned riporterebbe come guasta una configurazione funzionante.

Con dryRun non viene creato nulla. written è false, content contiene il documento che una scrittura avrebbe prodotto, e il file a cui è destinato quel contenuto è scope.configFile. Non viene creata alcuna directory e non viene toccato alcun file, così un editor può presentare il testo all’autore e lasciargli salvarlo, modificarlo o scartarlo.

Un dry run differisce da una scrittura per un solo aspetto — non scrive — quindi ogni rifiuto che esegue una scrittura lo esegue anche lui. Il rifiuto per file esistente è quello che conta qui: dryRun su un file di configurazione che esiste già viene rifiutato, indicando il file, esattamente come una scrittura. È questo che rende la risposta utilizzabile come predicato — se il dry run rifiuta, la scrittura avrebbe rifiutato, per lo stesso motivo e con lo stesso messaggio. Invia force insieme a dryRun per ricevere invece come risposta l’unione che produrrebbe una scrittura con sovrascrittura, sempre senza scrivere nulla. Il registry viene contattato per la sua politica di fiducia pubblicizzata con entrambe le modalità di consegna, perché la politica in quel contenuto è la politica che una scrittura avrebbe fissato.

Ciò che un congelamento riporta è ciò che ha scritto, non una sua descrizione. sockets elenca ogni socket di plugin che è stato congelato, con gli agganci congelati lì; catalogDirs contiene le directory del catalogo. Entrambi sono sempre array, vuoti anziché assenti.

  • socket e field non sono la stessa stringa, e la differenza non è estetica. socket indica il socket a cui sono vincolati gli agganci; field è la chiave sotto cui sono stati scritti nel file. Differiscono solo per il socket dei provider, che è scritto sotto una chiave al plurale — quindi usa field quando indichi a un lettore una riga del documento e socket quando nomini il socket stesso.
  • Ogni aggancio porta uri, capability, function e role, presenti solo dove l’aggancio ne ha uno. Identificano l’aggancio anziché riprodurlo per intero: gli input facoltativi che un aggancio riceve al momento dell’aggancio vengono congelati nel file alla lettera e non sono ripetuti nella risposta. Il file è la copia autorevole.
  • captured: false è un successo. Un progetto la cui configurazione non partecipa a una build non ha nulla di critico per la build da congelare, quindi il file resta com’è ed entrambe le liste tornano vuote. Trattarlo come un errore riporta come guasto un workspace sano.

L’impostazione predefinita congela solo ciò che determina i byte di output — i binding dei provider e gli agganci di governance che trasformano le etichette. I gate di verdetto della governance e dei linter e il socket di importazione restano esclusi, perché sono pensati per variare tra ambienti e congelarli porterebbe i gate di un ambiente in ogni checkout. allPlugins: true estende l’insieme a ogni socket di plugin. L’appartenenza è per aggancio, non per socket, quindi un socket di governance che porta un aggancio di trasformazione delle etichette e uno di verdetto contribuisce, con l’impostazione predefinita, solo con il primo.

Ogni valore viene congelato al suo valore effettivo — ciò che risulta unendo la configurazione della macchina e quella del progetto — così un binding che oggi proviene solo dalla configurazione della macchina viene scritto nel progetto e viaggia con esso. Le impostazioni degli strumenti a livello di macchina, tra cui la politica di fiducia di un registry, non sono critiche per la build e restano dove sono. Congelare due volte una configurazione invariata riscrive gli stessi byte, quindi un client può offrirlo liberamente: una seconda chiamata lascia il documento che un lettore tiene aperto esattamente com’era.

Cosa ti dice una modifica dei plugin

Le quattro richieste sui plugin scrivono tutte per impostazione predefinita, e si dividono in base a ciò che scrivono: due modificano un file di configurazione e due producono documenti nel workspace. Due di esse — l’aggiunta e la generazione — accettano dryRun, che fa tutto ciò che fa la richiesta tranne scrivere. Leggi il resoconto della risposta stessa su dove è finita la modifica anziché dedurlo dalla richiesta — per una di esse, una richiesta che non dice nulla sulla portata significa la portata più ampia.

Un’aggiunta e una rimozione portano entrambe scope, ricavato dal file a cui si è risolta la scrittura. configFile è quel file, machineWide dice se è quello attraverso cui si risolve ogni workspace su questa macchina, e workspaceRoot indica il workspace su cui è stata aperta questa sessione, così una risposta con ambito workspace dice di quale workspace si trattava. machineWide è ricavato dal file risolto anziché da ciò che la richiesta ha chiesto, ed è questo che impedisce a una risposta di descrivere una modifica a livello di macchina come locale.

🔴 Un’aggiunta di tipo cli che non indica né global né workspace registra il comando a livello di macchina. Un’estensione di comando è uno strumento a livello di macchina, quindi senza sostituzioni viene scritta nel file di configurazione globale attraverso cui si risolve ogni workspace su questa macchina — e il comando che registra diventa allora un comando aggrega di primo livello per ogni progetto su quella macchina, inclusi progetti che nessuno in questa sessione ha nominato. Un’aggiunta provider, governance, linter o importer funziona al contrario: queste determinano la build di un solo progetto, quindi senza sostituzioni vanno nel .aggrega-config.yaml di quel progetto. Una rimozione segue la stessa regola per gli stessi tipi. Invia workspace: true per mantenere locale un’estensione di comando, o global: true per spostare uno qualsiasi degli altri nel file condiviso; inviarli entrambi viene rifiutato. Lo scope nella risposta è in ogni caso la dichiarazione autorevole, e un client dovrebbe mostrarlo prima di agire sul risultato.

Un’aggiunta indica cosa è stato inserito, ed esattamente uno di tre campi dice di che genere di cosa si trattava. type ripete il tipo per cui è stata aggiunta la voce, e poi: identity contiene l’identità di entità nuda, fissata a una versione, per un aggancio governance, linter o importer; uri contiene l’indirizzo dell’artefatto oci:// del plugin, insieme alla capability che ora serve, per un binding provider; e reference contiene il riferimento fissato i cui comandi sono stati registrati per un’installazione cli. Così un chiamante legge dalla risposta quale genere di aggancio è stato inserito anziché ricavarlo di nuovo dal tipo che ha inviato. Una rimozione ripete type e query accanto al suo scope e nient’altro — non c’è altro da riportare su una voce che non c’è più.

Un’aggiunta porta anche written e, con dryRun, content. written è ciò su cui un client si dirama: true indica un file di configurazione ora su disco che il client può aprire, e con dryRun è false e content contiene invece il documento di configurazione che la scrittura avrebbe prodotto. I due non sono mai significativi entrambi, e il file a cui è destinato content è scope.configFile, quindi nulla nella risposta porta una seconda copia di quel percorso — il che qui conta, perché il file di un aggancio global è quello attraverso cui si risolve ogni workspace su questa macchina.

Un plugin senza alcuna versione pubblicata viene rifiutato anziché agganciato senza versione fissata. Un’aggiunta risolve la query in un solo plugin e ne fissa la versione pubblicata più alta, così la voce che scrive porta una versione. Un plugin il cui repository non pubblica alcuna versione conforme viene rifiutato indicandolo, e una versione ritirata da una retraction di cui questo workspace si fida viene scartata a favore della successiva inferiore.

Una versione nominata dalla query viene fissata anche quando è stata ritirata, e withdrawn lo segnala. Una query scritta come <name>:<version> fissa quella versione anziché la più recente — su ogni tipo tranne provider, che viene associato solo per nome e rifiuta una versione — e nominare una versione è l’override: dove una ritrattazione ritenuta attendibile da questo workspace l’ha ritirata, viene fissata comunque e la risposta riporta withdrawn: true — il fatto che aggrega plugin add segnala con una riga retraction: sul terminale. withdrawn è assente in ogni altra risposta, per cui la sua presenza è l’intero segnale — e la sua assenza non afferma che la versione non sia ritirata. Dove non è stato possibile leggere i marcatori di ritiro di una versione nominata, withdrawn è assente e retraction riporta unscreened, indicandone il motivo, come avviene per un’aggiunta che non nomina alcuna versione e incontra lo stesso errore; un’aggiunta che non nomina alcuna versione riporta invece in retraction ciò che il controllo dei ritiri ha concluso sulla versione scelta.

Un allineamento riporta se ha cambiato qualcosa, ed è quello il campo su cui agire. changed distingue una scrittura da un allineamento che ha trovato i record già corretti: un file invariato resta identico byte per byte, quindi un client che tiene quel documento non ha nulla da ricaricare, ed eseguire la richiesta due volte non riporta alcuna modifica la seconda volta. entity indica il file, hostFunctions contiene l’insieme derivato, e commands contiene il rispecchiamento come valori anziché come la riga che stampa un terminale — ogni voce con un name, una description facoltativa e flags, ogni flag con il suo name e i facoltativi shorthand, description, type e default. La scrittura è atomica, quindi un client che legge quel file mentre l’allineamento è in corso non osserva mai un documento parziale.

Una generazione riempie esattamente una metà della sua risposta, e il dryRun della risposta stessa dice quale. Con l’impostazione predefinita le entità vengono scritte e notices contiene ciò che la generazione ha detto sulle scritture eseguite. Con dryRun non viene creato né modificato nulla: documents contiene ogni entità generata come il path a cui è destinata e il suo content, così un client può inserirle nel proprio modello di documento, dove sono visibili prima di essere salvate e possono essere modificate o scartate. Le due metà non sono mai riempite entrambe, quindi quale modalità di consegna è stata eseguita si legge dalla risposta anziché da ciò che è stato chiesto.

Dove una richiesta sui plugin SCRIVE è sempre all’interno del workspace indicato da quella richiesta; ciò che LEGGE si decide campo per campo. Una destinazione assoluta, una che risale fuori dalla radice e una che ne esce attraverso un link vengono rifiutate anziché risolte — così una generazione non può creare entità in un albero su cui la tua sessione non è mai stata aperta, qualunque cosa invii. Un percorso che una richiesta si limita a leggere è una questione separata, a cui si risponde campo per campo anziché con un’unica regola per tutti: aggrega/pluginGenCatalog legge un modulo e il suo overlay da dove li hai selezionati, perché un modulo che hai compilato si trova nella directory di output della tua toolchain e rifiutarsi di leggerlo lì significherebbe rifiutare l’operazione nel suo stesso scopo. aggrega/pluginSync legge i suoi due percorsi all’interno del workspace, perché quella richiesta riguarda un file che il workspace contiene già. Le richieste di localizzazione precedenti accettano un percorso assoluto per un motivo ancora diverso — un documento che il client tiene già aperto, indicato con la grafia che usa.

Una richiesta a cui manca qualcosa di cui l’operazione ha bisogno viene rifiutata indicando il campo da inviare. Un’aggiunta o una rimozione senza type o query; un’aggiunta provider senza capability, o una governance senza role; un’aggiunta cli senza acceptCapabilities; un allineamento senza entity o plugin; una generazione che indica entrambe le modalità di selezione o nessuna, o a cui mancano overlay o outputDir. Ciascuna torna con il codice invalid-params standard, e un nuovo tentativo non cambia nulla finché la richiesta non cambia. Viene rifiutata anche una rimozione la cui query non corrisponde ad alcuna voce, indicando il tipo, la query e il file in cui ha cercato — quello è uno stato della configurazione anziché della richiesta, quindi ciò da correggere può essere l’una o l’altra.

Non viene chiesto nulla in modo interattivo, e l’unica decisione che si sarebbe chiesta a una persona arriva invece come campo. Il comando da terminale chiede a chi sta guardando se accetta le capability dichiarate di un plugin di estensione di comando. Nessuno sta guardando questo flusso, quindi spetta al chiamante ottenere e inviare acceptCapabilities, e una richiesta che non lo contiene viene rifiutata indicando cosa inviare, anziché installare sulla base di un consenso che nessuno ha dato. Un daemon avviato senza i mezzi per installare un’estensione di comando rifiuta del tutto un’aggiunta cli, anziché riportare un successo che non ha installato nulla.

Quali tipi puoi proporre a un autore

aggrega/getSchema senza kind risponde quali tipi puoi indicare, e risponde con due ampiezze perché un client ne ha bisogno di una diversa per un compito diverso. Leggi quella che stai chiedendo.

kinds è ogni token a cui il binario risponde. entityKinds è l’insieme di cui un autore scrive un documento. La lista ampia contiene la rappresentazione intermedia, il lockfile, la configurazione del workspace e i contratti dei socket dei plugin accanto ai tipi che scrivi — schemi reali, ciascuno, ma non documenti di cui qualcuno scriva un file. Quindi la lista ampia è quella da cui collegare l’associazione degli schemi di un editor, e quella ristretta è quella da cui costruire un selettore. Un selettore costruito dalla lista ampia offre valori che nessuno schema di authoring accetta, e l’autore incontra il rifiuto solo dopo averne scelto uno.

L’insieme ristretto è più ristretto anche dei tipi di entità, e nessuno schema ti dice quali. Un tipo di proprietà della piattaforma il cui contenuto è scritto dentro il documento di un altro tipo non è un documento da proporre a un autore per iniziare. Workload è un tipo di questo genere: il contenuto del workload si scrive nel campo workload: di una Recipe o di una FeatureRecipe, inline o da un file che quel campo importa, quindi non esiste alcun documento workload da indirizzare a sé — vedi la superficie di authoring del Workload per sapere dove va quel contenuto. Il suo schema fissa apiVersion e kind esattamente come fa lo schema di un tipo scritto dagli autori, perché è ciò che permette di validare il contenuto dove si trova; i valori fissi identificano il contenuto e non lo rendono indirizzabile. Quindi non sono un segnale che un tipo sia da abbozzare. entityKinds porta la risposta, e nulla nei byte dello schema lo fa.

Ogni voce di entityKinds porta entrambe le grafie di cui un client ha bisogno, e nessuna delle due è ricavabile dall’altra. kind è il token minuscolo con trattini — rimandalo come kind a questo metodo o a aggrega/scaffoldEntity. documentKind è il valore che il documento stesso porta nel suo campo kind: di primo livello. I due differiscono per più che le maiuscole per un tipo il cui nome è composto da più di una parola: niente di ciò che puoi fare a featurerecipe arriva a FeatureRecipe. Prendi ciascuno dalla voce anziché ricavare l’uno dall’altro, e al client non resta alcuna corrispondenza da mantenere.

Ogni voce dice anche quali operazioni accettano un documento del suo tipo, così un controllo che offre quelle operazioni su un documento offre solo quelle che non lo rifiutano per il suo tipo. acceptedBy porta tre booleani, ciascuno presente in ogni voce, e ciascuno riguarda un documento del tipo indicato da solo — tramite il suo percorso, o tramite il suo nome per l’ispezione — senza nient’altro inviato accanto. singleEntityValidation indica se aggrega validate <path> verifica un documento del tipo, anziché rifiutarlo e indicare l’ambito dell’intero catalogo o della Release che invece lo verifica. publication indica se aggrega/publishEntity che indica solo il documento lo pubblica: un Plugin è false, perché la sua pubblicazione vincola anche l’eseguibile che una richiesta indica in plugin, quindi una richiesta che indica solo il documento viene rifiutata; un Manifest e una Release sono false perché nessuno dei due tipi viene pubblicato. inspectionByName indica se aggrega/entityDefinition risolve un nome in un’entità del tipo, con il nome inviato così come è scritto dove un’entità ne referenzia un’altra — un Plugin come <pluginType>/<name>, e una Recipe o una FeatureRecipe come <capability>/<name>, o con il solo nome dove una sola capability dichiara quel nome. Un true dice che l’operazione non rifiuta il documento perché è di quel tipo; può comunque rifiutare un documento particolare per ciò che il documento dice.

Non tenere una lista tua. Quali tipi esistono è una proprietà del binario con cui stai parlando, quindi una lista scritta in un client concorda il giorno in cui viene scritta e smette di concordare il giorno in cui viene aggiunto un tipo — e ciò che l’autore vede allora è il proprio tipo assente dall’unico controllo che avrebbe dovuto offrirlo. Chiedi, e la risposta segue il binario.

Le due metà arrivano insieme, e solo quando non indichi alcun tipo. Una richiesta che indica un tipo risponde con lo schema di quel tipo e non porta nessuna delle due liste, così quale domanda hai posto si legge dalla risposta. Un token a cui nessuno schema risponde viene rifiutato con l’intero insieme valido nel messaggio, con il codice invalid-params standard, così un refuso è una richiesta da correggere anziché qualcosa da chiedere a una persona.

Risponde in un workspace che non contiene nulla. Il vocabolario è compilato nel binario, quindi non servono documenti, lockfile né catalogo — ed è proprio il workspace in cui si trova un autore che inizia il suo primo documento.

Che cosa ti fornisce una risposta di scaffold

Questa sezione riguarda la stesura di bozze. L’altra forma del metodo scrive un esempio eseguibile, e la sua risposta è descritta insieme al metodo più sopra.

aggrega/scaffoldEntity restituisce del testo. skeleton è YAML per il tipo che hai indicato: ogni campo che lo schema di quel tipo richiede, nell’ordine in cui lo schema li dichiara. Un campo che lo schema fissa a un unico valore arriva già compilato — apiVersion e kind sono quelli che noterai — metadata.name porta il name che hai inviato, e ogni altro valore obbligatorio arriva come segnaposto del tipo che lo schema dichiara in quel punto: una stringa vuota, uno zero, un false, una lista vuota, una mappa vuota. kind ripete il token per cui il documento è stato derivato, così un client con più richieste in sospeso attribuisce una risposta a partire dalla risposta stessa anziché mantenere una propria correlazione.

Non scrive nulla, ed è attorno a questo che va progettato. Il metodo non crea alcun file, non sceglie alcun percorso e non tocca alcuna directory. Ciò che ricevi è un documento da scrivere, non un documento che è stato scritto — quindi un editor mette il testo in un nuovo buffer non salvato che l’autore può leggere, modificare o scartare, e il momento in cui un nuovo file raggiunge il disco resta lì dove sono il buffer e la cronologia degli annullamenti. Nessun’altra richiesta prende questo documento e lo mette da qualche parte per tuo conto; decidere dove risiede un nuovo documento spetta all’editor.

Non risolve nulla e non ha bisogno di nulla dal workspace. Il documento è derivato dagli schemi contenuti nel binario, quindi il metodo non raggiunge alcun registry né alcuna rete, non consulta alcun catalogo e non legge alcun file. Risponde allo stesso modo in ogni workspace, compresa una directory vuota che non contiene ancora alcun documento Aggrega — che è esattamente il workspace in cui si trova un autore che inizia il suo primo documento, e dove la maggior parte degli altri metodi qui vorrebbe prima un documento o un lockfile.

La stessa richiesta dà gli stessi byte ovunque venga posta. Il documento è prodotto da un unico calcolo condiviso con le altre superfici che offrono questa capacità, quindi un editor e un assistente a cui si chiedono lo stesso tipo e lo stesso nome mostrano all’autore lo stesso testo di partenza.

Lo scheletro porta i campi che il suo tipo richiede, e non è un documento finito. Porta i campi obbligatori e nient’altro: un campo facoltativo che vuoi è uno che aggiungi tu, e ogni segnaposto è un valore ancora dovuto. Compila i segnaposto, poi esegui aggrega/validate sul buffer. Per un’entità di catalogo di un tipo che aggrega validate verifica come singola entità, quel metodo nomina ogni segnaposto ancora dovuto, ciascuno nella sua chiave con ciò che accetta, secondo la stessa lettura che il comando applica al file salvato — compreso un segnaposto che lo schema ammette vuoto, e capability e implements di una Recipe o FeatureRecipe abbozzata sono quelli che incontrerai. Per qualsiasi altro tipo sottopone il buffer allo schema del suo tipo, quindi un segnaposto che lo schema rifiuta vuoto — una versione, ad esempio — torna come rilievo di quello schema, e uno che lo schema ammette vuoto non ne produce alcuno. Convalida in tempo reale descrive la voce con cui arriva ciascun segnaposto.

Che cosa ti dice una risposta di import

aggrega/import converte un sorgente scritto per un altro strumento in bozze di documenti Aggrega, e le scrive — a differenza dello scaffold descritto sopra, che ti restituisce testo. written indica ogni file arrivato su disco, relativo a outputDir; files riporta ogni file che la richiesta scrive con il suo content, che sia stato scritto o no — ogni bozza prodotta dall’importer, poi il registro di ciò che l’import ha scritto, oppure, con sync, ciò che la sincronizzazione cambia. I due rispondono a domande diverse, quindi leggi quello che corrisponde alla domanda che ti stai ponendo: che cosa c’è ora su disco, o che cosa è stato prodotto.

Scegli tu dove vanno le bozze, oppure lasci decidere alla radice del workspace. outputDir è facoltativo, come lo sono aggrega import --output-dir e l’output_dir dello strumento import dell’assistente: una richiesta che non ne indica nessuno crea le bozze sotto la radice del workspace — dove scrive aggrega import quando non riceve una destinazione, ovunque venga eseguito — e una richiesta che ne indica una crea le bozze lì. Una directory indicata è un percorso all’interno del workspace, e un valore relativo si risolve rispetto alla radice del workspace anziché rispetto a una directory in cui il daemon si trovi per caso. Il source che converti è l’altro caso e non è confinato in questo modo: quel file o quella directory li hai selezionati tu, quindi viene letto ovunque si trovi, e leggerlo lì non sposta il punto in cui finiscono le bozze. La directory viene creata se non esiste. Con dryRun non viene scritto nulla, e ogni bozza indica comunque il percorso a cui è destinata, relativo all’outputDir indicato dalla risposta — la directory che hai inviato, oppure la radice del workspace.

Una richiesta non sovrascrive mai un Aggregate già presente in outputDir. Un Aggregate è il documento che un autore continua a modificare una volta creato in bozza, quindi una richiesta in cui una delle bozze finirebbe su un file che si legge come un Aggregate viene rifiutata, indicando la bozza e dove si trova l’Aggregate, e non viene scritto assolutamente nulla — anche con dryRun, poiché una dry run rifiuta ciò che la scrittura rifiuta. Invia invece sync per aggiornarlo rispetto al sorgente, oppure indica un altro outputDir per creare la bozza accanto a esso. Ogni altro file già presente in un percorso di bozza viene sovrascritto, e un file creato in bozza da un import precedente che questo non crea viene lasciato dov’è. Ogni richiesta che crea una qualsiasi bozza scrive anche .aggrega-import.json in outputDir, il registro di ciò che l’import ha scritto — il target ricevuto, dove ne ha ricevuto uno, l’istantanea del catalogo letta, dove ne ha letta una, e ogni file in bozza e, in un Aggregate o in una Release in bozza, ogni chiave a ogni profondità, con un digest del testo scritto lì, mentre ogni altro file in bozza viene registrato per intero — e files e written lo riportano dopo le bozze. È JSON, quindi nulla di ciò che legge i documenti YAML del workspace lo legge; sync, come aggrega import --sync, lo legge per aggiornare le bozze rispetto al loro sorgente. Un sync inviato senza target crea le bozze per il target indicato dal registro, quindi crea in bozza il Manifest che l’import precedente aveva creato; uno inviato con un target crea le bozze per quel target, e il registro poi indica quello. Un target registrato a cui nessuna Recipe del catalogo si lega viene rifiutato come lo è uno inviato, e il rifiuto dice che il target è quello registrato. Poiché una Release in bozza è registrata chiave per chiave, l’ambiente che il suo autore scrive dove l’import ha lasciato un commento apposito è una chiave scritta dall’autore, e una sincronizzazione la lascia identica byte per byte.

Invia sync per aggiornare rispetto al sorgente ciò che un import precedente ha creato in bozza in outputDir, cambiando solo ciò che l’import ha scritto. Ogni parte viene valutata in tre modi — ciò che il registro dice che l’import vi ha scritto l’ultima volta, ciò che c’è su disco e ciò che il sorgente produce ora. Una parte che il sorgente ha lasciato come l’import l’aveva scritta l’ultima volta resta esattamente com’è su disco, che un autore l’abbia modificata o no. Una parte che il sorgente ha cambiato viene riscritta, una parte che ha eliminato viene rimossa — un file in bozza viene cancellato per intero — e una parte che ha acquisito viene aggiunta accanto alle parti che la bozza indica intorno a essa, ciascuna solo dove ciò che c’è su disco è ciò che l’import ha scritto l’ultima volta e non contiene nulla aggiunto da un autore. Tutto il resto rimane identico byte per byte: una chiave che un autore ha aggiunto in qualsiasi punto — un parametro, una Feature, anche sotto un’istanza di Component in bozza, un altro Component — un commento non scritto direttamente sopra una chiave in bozza, e ogni file che il registro non elenca. Una sincronizzazione in una directory che non contiene alcun registro e nulla nei suoi percorsi di bozza scrive l’intera bozza, come fa una richiesta senza sync.

drift è ciò che una sincronizzazione ha aggiornato, ed è la risposta a «il sorgente è cambiato?». Elenca ogni parte che la sincronizzazione ha cambiato — oppure, con dryRun, ogni parte che cambierebbe — nell’ordine in cui la bozza le indica, ciascuna come change (added, removed o changed), file, il file in bozza in cui si trova, relativo a outputDir, e key, le chiavi che vi conducono in un Aggregate o in una Release in bozza sotto forma di lista, così una chiave che contiene un punto resta un’unica voce; key è vuoto dove la parte è l’intero file, ed è così che viene indicato un file in bozza che la sincronizzazione cancella. aggrega import stampa le stesse voci sullo standard error come <change> <key> in <file> o <change> <file>, e il suo exit status con --sync --dry-run dice se il sorgente è cambiato; questa superficie non ha exit status, quindi invia sync con dryRun e verifica se drift è vuoto. drift è una lista vuota per una richiesta che non è una sincronizzazione, per una sincronizzazione allineata al proprio sorgente e per una sincronizzazione il cui importer non è riuscito a terminare. Con sync, files riporta ogni file in bozza che la sincronizzazione cambia, con il contenuto che gli assegna, poi il registro dove cambia anch’esso, e written indica quelli arrivati su disco — quindi una sincronizzazione allineata risponde a entrambi con liste vuote. Un file in bozza che la sincronizzazione cancella è indicato in drift e in nessuna delle due liste: la sua voce removed, con una key vuota, è l’unico resoconto che la risposta ne dà, e con dryRun indica il file che una scrittura cancellerebbe.

Una sincronizzazione non riscrive mai ciò che un autore ha scritto, e rifiuta invece. Una sincronizzazione che cambierebbe o rimuoverebbe una parte modificata da un autore, aggiungerebbe una parte dove un autore ne ha già scritta una, o rimuoverebbe una parte contenente qualcosa aggiunto da un autore viene rifiutata, indicando ciascuna di queste parti e il motivo su una riga a sé, con le parole che usa aggrega import --sync — <file> <key>: <why>, oppure <file>: <why> per un intero file — e non viene scritto nulla; un commento scritto direttamente sopra una chiave in bozza modifica quella chiave. Una sincronizzazione su un Aggregate che nessun registro elenca viene rifiutata indicando l’Aggregate e il registro, così come una il cui registro non può essere letto, poiché senza il registro le sue parti non si possono distinguere da quelle di un autore. Entrambi i rifiuti tornano come errore invalid-params, anche con dryRun, e indicano sync. Riconcilia a mano ogni parte indicata, oppure ripristina ciò che l’import vi aveva scritto, e invia di nuovo la richiesta.

🔴 halted: true non è un errore, e trattarlo come tale è lo sbaglio da prevenire nella progettazione. Un importer che non è riuscito a convertire tutto crea comunque le bozze di ciò che ha potuto: la risposta contiene quelle bozze, written le indica e diagnostics dice che cosa è stato tralasciato. È la risposta più utile che l’operazione dà, e arriva come risultato anziché come fallimento proprio perché tu possa mostrare all’autore entrambe le metà. Con sync la stessa risposta non scrive nulla — files, written e drift sono vuoti — perché una bozza parziale si leggerebbe come un sorgente che ha eliminato ogni parte che l’importer non ha raggiunto. Un sorgente che l’importer non è riuscito a leggere affatto è un caso diverso e torna effettivamente come errore.

Ogni diagnostica riporta severity e message, più code dove l’importer ne ha assegnato uno. Ramifica su code quando vuoi reagire a una condizione specifica e mostra message al lettore; severity è tratto dallo stesso insieme in cui riporta ogni socket di plugin — halt, warn, info — quindi halted è un riepilogo delle voci anziché un giudizio separato. files, written, drift, diagnostics e decisions sono sempre array, vuoti anziché assenti.

decisions dice dove l’import ha tirato a indovinare. Contiene una voce per ogni nodo sorgente che l’importer ha mappato, nell’ordine dell’importer ed esattamente come l’importer l’ha riportato: sourceNode, l’id, il type e il paramsSummary del nodo; candidates, ogni Component del catalogo che l’importer ha valutato per esso come componentName, score, tier e signals — ciò che ciascuno dei suoi segnali ha contribuito, sotto table, category, domainLabels, shape e name; chosen, il target scelto, il mode in cui l’ha scritto — un reference a un Component esistente o un draft — e il tier della scelta; rationale, il perché; e swapHint, come scegliere diversamente. candidates è assente dove l’importer non ne ha valutato nessuno, chosen dove non ha fatto alcuna scelta, e rationale e swapHint dove non ne ha scritto. Ogni valore è dell’importer stesso — come assegna il punteggio a un candidato e dove cadono i suoi livelli sono scelte sue — quindi mostra una voce come il suo resoconto della mappatura anziché come un verdetto. Le decisioni arrivano sia con dryRun sia con halted vero: le ipotesi di un import parziale sono esattamente ciò di cui ha bisogno un autore che lo rivede, e un importer che non ne riporta nessuna risponde con una lista vuota. Dove le mostri come testo, aggrega import formula già una decisione come mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, dove il punteggio è quello del candidato migliore.

Il formato viene riconosciuto dal sorgente, a meno che tu non lo indichi. Il riconoscimento usa le firme che gli importer dichiarano — sia quelli del catalogo del workspace sia gli importer core del compilatore — registrate dall’entità Plugin di ciascun importer — la sintassi in cui si legge un sorgente, i nomi di file a cui si applica una firma e i percorsi che l’albero analizzato deve o non deve contenere — quindi il daemon stesso non conosce alcun formato e il formato di un nuovo importer viene riconosciuto senza cambiare nient’altro. Il rilevamento legge solo il sorgente che hai inviato — di una directory, solo i file selezionati dai pattern di file di una firma — e nessuna rete, analizzando ogni file che legge con il parser che il catalogo del workspace fornisce per una sintassi — oppure, per una sintassi per cui il catalogo non fornisce alcun parser, quello incluso nel compilatore stesso — una volta per ogni sintassi in cui lo legge una firma che si applica al suo nome; l’importer legge poi il sorgente con lo stesso parser. Una firma che non dichiara alcun pattern di file si applica al file che hai inviato, comunque si chiami, e a nessun file di una directory; le firme degli importer Langflow, Flowise e n8n sono di questo tipo e leggono JSON, e quella dell’importer Dify legge YAML, quindi riconoscere un file inviato da solo significa leggerlo come JSON e come YAML, il che non richiede alcun parser nel catalogo del workspace: il compilatore include un parser JSON e uno YAML, e uno fornito dal catalogo viene usato al loro posto. Un sorgente che nessuna firma riconosce viene rifiutato chiedendo format e indicando i formati che gli importer dichiarano — oppure, per una directory, chiedendo uno dei suoi file inviato da solo o un format il cui importer dichiara pattern di file, indicando solo quelli — con la condizione No importer recognises the source (Nessun importer riconosce il sorgente); un sorgente riconosciuto da firme di più di un formato viene rifiutato indicandoli, con la condizione More than one importer recognises the source (Più di un importer riconosce il sorgente). Il data di ciascun rifiuto riporta il code e lo shortCode della sua condizione, così un client chiede il formato in base al codice anziché alle parole. Nessuno dei due viene indovinato, perché un formato indovinato risolve l’importer sbagliato e produce assurdità presentate con sicurezza. format nella risposta è quello usato, rilevato o indicato, così un client che lo ha omesso scopre che cosa ha ottenuto.

Una directory che invii viene letta nei file che il suo importer indica, e una che non può essere letta è un errore. Dove source indica una directory, all’importer vengono consegnati i suoi file selezionati dai pattern di file dichiarati dalle sue firme, esclusa la cartella di output della build del workspace dist/, ciascuno indicato con il suo percorso all’interno della directory, in ordine, accanto ai file che la sua voce plugins.importer indica sotto with.sources. Un importer che non dichiara pattern di file, una directory che non contiene alcun file da essi selezionato, un file della directory e un file di with.sources con lo stesso nome, e un link tra i file che l’import leggerebbe, o verso una directory, che porta fuori dalla directory tornano ciascuno come errore che riporta il codice della condizione, senza che venga scritto nulla.

Quale importer viene eseguito è una decisione del workspace, non della richiesta. Il formato si risolve nell’importer che lo dichiara tra i plugin del catalogo del workspace e gli importer core del compilatore — quello che una voce plugins.importer nella configurazione del workspace collega, dove ne collega uno — quindi una richiesta non può selezionare un modulo né puntare a uno su disco. Un formato che nessun importer dichiara viene rifiutato indicando il formato, e un formato dichiarato da due importer senza che nessuno dei due sia collegato — tra cui un importer core e un importer di altro nome che il catalogo contiene per lo stesso formato — viene rifiutato come ambiguo anziché risolto arbitrariamente.

Un importer core che la macchina non possiede ancora viene scaricato una volta, dal primo import che ne ha bisogno. Proviene dal registry predefinito del workspace, vincolato al modulo pubblicato dalla release del compilatore e verificato come una pull verifica un plugin che scarica — la sua firma secondo la policy di fiducia di quel registry e le funzioni host che usa — e viene conservato nella cache dei contenuti del workspace, che è l’unica cosa scritta per esso: nessun lockfile e nessun registro dei plugin attendibili. Ogni import successivo lo legge da lì e non contatta alcun registry. Un modulo che non supera la verifica è un errore che riporta il codice della sua condizione, e non viene conservato nulla; uno che non può essere scaricato — il workspace è offline, il suo registry non è raggiungibile, o il registry non lo contiene — è un errore con A plugin’s .wasm is not on this machine (Il modulo di un plugin non è su questa macchina), che indica l’importer, la sua versione e che cosa mette il suo modulo sulla macchina. La richiesta stessa non indica alcun registry, e un import che ha già sulla macchina ogni importer e il catalogo che legge non contatta affatto la rete.

Dove il workspace non indica alcuna cartella di catalogo, l’import legge il catalogo pubblicato dal suo registry predefinito. Un workspace in cui né workspace.catalog_dirs, né AGGREGA_CATALOG_DIRS, né la radice indicano una cartella di catalogo legge il catalogo della libreria standard come un’unica istantanea firmata, in catalog/snapshot sul suo registry predefinito. Un’istantanea viene scaricata una sola volta: la sua firma viene verificata secondo la policy di fiducia di quel registry, e viene conservata nella cache dei contenuti del workspace e letta lì come una cartella di catalogo, vincolata al suo digest, senza che venga più richiesta ad alcun registry. Quale istantanea legge una richiesta: con upgrade, la più recente; altrimenti quella indicata dal registro in outputDir, scaricata tramite il suo digest dove la macchina non la possiede; altrimenti quella che il workspace ha scaricato per ultima come la più recente; altrimenti la più recente. Il registro che l’import scrive indica l’istantanea letta, tramite il suo digest, così una richiesta successiva nello stesso outputDir legge lo stesso catalogo. In modalità offline una richiesta che dovrebbe scaricare un’istantanea è un errore con The workspace is offline and the step needs the network (Il workspace è offline e il passaggio richiede la rete), che indica che cosa eseguire, e upgrade viene rifiutato qualunque cosa possieda la macchina, poiché solo il registry può dire quale istantanea sia la più recente. Un registry che non pubblica alcuna istantanea lascia l’import senza catalogo, e una voce warn in diagnostics lo segnala. Un workspace che indica una cartella di catalogo esegue l’import rispetto a essa e non scarica alcuna istantanea, e lì upgrade non cambia nulla.

Con dryRun non viene creato nulla. written è vuoto, files riporta gli stessi file che una scrittura avrebbe prodotto — con sync, i file che la sincronizzazione scriverebbe, accanto al drift che aggiornerebbe — e non viene creata alcuna directory — così un editor può presentarli all’autore perché li salvi, li modifichi o li scarti. Tutto il resto che fa una scrittura viene fatto: lo stesso importer viene eseguito sullo stesso sorgente e riporta le stesse diagnostiche, quindi un sorgente che una scrittura rifiuterebbe viene rifiutato anche qui. Un importer core o un’istantanea del catalogo scaricati con dryRun vengono conservati nella cache dei contenuti come con una scrittura, perché acquisire ciò su cui l’import viene eseguito fa parte dell’eseguirlo anziché del collocare le bozze.

Un percorso restituito dall’importer è vincolato all’interno di outputDir. I percorsi delle bozze provengono dall’importer anziché da te, quindi un percorso che risale fuori dalla directory di output viene rifiutato e non viene scritto assolutamente nulla — nemmeno le bozze i cui percorsi erano corretti. Il rifiuto indica il percorso incriminato, ed è questo che ti dice che è l’importer a dover essere corretto e non la tua richiesta.

A quale domanda risponde ogni richiesta sulle entità

Quattro richieste qui ti informano su un’entità, e non sono intercambiabili. Scegliere tra di esse è una questione di che cosa hai in mano quando chiedi.

Hai in mano un cursore. aggrega/hover e aggrega/resolve prendono un file e una posizione e ricavano quale entità si intende da ciò che vi è scritto. Coprono le forme di riferimento che un documento contiene davvero — un valore extends, un tipo di componente o di feature, gli implements di una Recipe, i riferimenti a recipe di un Manifest, i due puntatori di percorso di una Release, un target di uses e il metadata.name dell’entità stessa. Usale quando la coordinata è il cursore dell’utente: l’utente sta leggendo un documento e vuole sapere a che cosa punta un riferimento.

Hai in mano un nome. aggrega/entityDefinition prende direttamente l’identità. Non deve essere aperto nulla, non è coinvolta alcuna posizione, e l’entità non deve essere menzionata in alcun punto che il client possa trovare. Usala quando l’utente ha digitato un nome, ne ha scelto uno da un elenco, o ha seguito qualcosa di cui il tuo client conosce già l’identità — un hover richiede prima di trovare un punto in cui il nome è scritto, un lavoro che non devi fare.

Non hai ancora in mano nulla. aggrega/catalogIndex enumera ciò che il workspace contiene, con i campi descrittivi di ogni entità. Usala per popolare un selettore, poi passa un nome scelto a aggrega/entityDefinition.

Hai in mano una Release. aggrega/releaseClosure risponde su una Release anziché su una singola entità, ed è la sezione seguente.

La definizione che restituisce una richiesta per nome è l’entità così come risolta, non come la dichiara un singolo file. Un Component o una Feature che estende una base torna con il contratto di quella base, che non compare da nessuna parte nel documento che ne dichiara il nome — quindi la risposta riguarda ciò che l’entità è, e leggere tu stesso il file non ti darebbe la stessa cosa.

Arriva come documento YAML anziché come struttura all’interno della risposta, ed è voluto: un pilastro dello schema ha diverse forme di authoring — contenuto scritto per esteso, un riferimento a un documento condiviso, o il marcatore che indica che il contenuto proviene da una base — e il documento riproduce quella a cui è arrivata la risoluzione, nell’ordine delle chiavi dell’autore stesso. Analizzalo come documento se ti servono i suoi campi; mostralo così com’è se lo stai inserendo in un pannello.

Distinguere i due rifiuti per nome

Un nome che non si risolve in nulla viene rifiutato anziché ricevere come risposta un documento vuoto, perché una risposta vuota presenterebbe un refuso come un’entità che non ha nulla da dire su di sé. Ci sono due modi in cui un nome non si risolve in nulla, richiedono cose diverse al lettore, e li distingui da ciò che riporta il data dell’errore, non leggendo il messaggio:

  • Nessun file in data. Nulla nel workspace dichiara quel nome e nessun livello del catalogo lo risolve. Quasi sempre è la richiesta a dover essere corretta — un refuso, o un nome di un catalogo che questo workspace non ha nel suo percorso di ricerca.
  • Un file in data. Un documento del workspace dichiara effettivamente quel nome, e il catalogo non ha comunque risolto nulla per esso. L’entità è scritta e qualcosa l’ha rifiutata, il che è uno stato del workspace che una persona ripara. Dove esattamente un documento letto e rifiutato dal catalogo dichiara quel nome — la causa abituale — il messaggio apre con quel rifiuto, enunciato una sola volta: la sua categoria e il suo codice breve, il documento con il percorso con cui viene riportato, e che cosa non va in esso, come la riga e il vincolo che viola; poi segnala che il file è stato saltato al caricamento ed elenca ogni altro file che il caricamento ha rifiutato. Altrimenti il messaggio indica il documento dichiarante, elenca i file che il caricamento ha rifiutato e dice da dove questo workspace legge le entità locali e che cosa cambiare perché il documento venga letto — la spiegazione che omette quando un documento rifiutato dichiara il nome, perché quel documento si trova già dove il catalogo legge.

Entrambi riportano il codice entity-not-resolvable, quindi ramifica sulla presenza di file anziché sul codice.

Interrogare una coordinata

Hai in mano un riferimento a un registry. Invialo come name di aggrega/entityDefinition, e la risposta è l’entità pubblicata a quella coordinata, nella stessa forma di risultato che ottiene un nome più published, compilata a partire da ciò che è stato pubblicato anziché da ciò che un catalogo ha risolto:

  • definition è il documento dell’entità esattamente come è stato pubblicato. Una coordinata la cui entità è stata pubblicata con i file che dichiara contiene un archivio, e il documento viene estratto da esso; una la cui entità non dichiara alcun file contiene il suo documento invariato, e l’entità di un Plugin viene letta dal suo manifest anziché dall’eseguibile pubblicato con esso. Non viene applicata alcuna ereditarietà.
  • authoredLength è la lunghezza di quel documento, perché qui la definizione è un documento scritto dall’autore anziché la resa di uno risolto.
  • file è vuoto, perché un’entità letta da un registry non ha su questa macchina alcun documento da indicare.
  • publishScope è omesso: hai già in mano la coordinata, che è il punto in cui l’entità è pubblicata.
  • published è ciò che è stato letto, ed è presente in questa risposta e in nessuna per nome: il reference; archive, se i suoi byte erano un archivio da cui è stato estratto il documento — false dove la coordinata conteneva il documento stesso; il mediaType che il manifest dichiara; e il manifestDigest di quel manifest, che puoi inviare dopo @ al posto del tag per rileggere esattamente gli stessi byte.

La richiesta raggiunge il registry indicato dal riferimento, con le credenziali dell’utente con cui viene eseguito questo daemon e la postura di rete di questo workspace, quindi un workspace offline la rifiuta. I byte scaricati vengono confrontati con il digest che il manifest dell’artefatto stesso registra per essi e con nient’altro — non viene verificata alcuna firma e non viene segnalato alcun ritiro — e non viene scritto nulla. Un riferimento che non può essere letto viene rifiutato con entity-not-resolvable, e il messaggio si apre con il codice breve della condizione che spiega il motivo — le stesse condizioni che riporta aggrega inspect — e termina con che cosa fare al riguardo. Un riferimento che non indica alcun repository, o né un tag né un digest, è una richiesta malformata e viene rifiutato come parametri non validi.

Una chiusura non è il grafo

aggrega/irGraph e aggrega/releaseClosure derivano dalla stessa risoluzione della stessa Release e rispondono a domande diverse. Un client che riceve già il grafo può ragionevolmente presumere di avere anche questa, e non è così.

Il grafo dice che cosa distribuisce la Release — i suoi nodi, i confini in cui si trovano, che cosa è collegato a che cosa, e i valori e gli allegati che ogni nodo contiene. È l’immagine.

La chiusura dice che cosa è stato incluso per costruirla, e in quali versioni. Ogni entità che la Release raggiunge, che sia diventata un nodo o no; i documenti condivisi a cui quelle entità attingono; e i plugin che danno forma all’output. È la distinta base.

Nessuna delle due è ricavabile dall’altra. Un’entità può essere raggiunta senza mai comparire come nodo — la Recipe a cui un Manifest mappa un tipo di componente viene raggiunta da ogni build e non è un nodo in nessuna di esse — e un nodo non riporta la versione in cui si è risolto il suo tipo. Quindi un lettore che chiede «perché è cambiata questa versione?», «che cosa influenzerebbe la modifica di questo documento condiviso?» o «da che cosa dipende davvero questa Release?» sta chiedendo la chiusura, e un lettore che chiede «che cosa distribuisce questa Release?» sta chiedendo il grafo.

Che cosa non fa la richiesta di chiusura. Non esegue alcun rendering e non pubblica nulla di ciò che trova. In particolare non solleva alcun avviso di drift né alcun avviso di rendering: quelli appartengono alla richiesta che li ha chiesti, e la pubblicazione sostituisce un intero livello di diagnostica, quindi un elenco che pubblicasse cancellerebbe ciò che la richiesta del grafo aveva già messo davanti all’utente. Chiedi il grafo quando vuoi il verdetto sul drift. L’unica cosa che pubblica non è una sua constatazione: una richiesta che trova il lockfile scomparso ritira l’avviso di drift che si basava su di esso, qualunque richiesta sia — vedi Consapevolezza del lockfile.

Richiede un lockfile, come il grafo. Le versioni riportate dall’elenco sono quelle in cui si è risolta questa Release, e un workspace che nessuno ha preparato non le ha ancora risolte. Un elenco prodotto senza lockfile riporterebbe ciò che il catalogo contiene per caso oggi, che è una domanda diversa da ciò da cui dipende questa Release. Il rifiuto indica il lockfile e la Release, così un client può proporre direttamente aggrega pull --release <release>.

kind in una voce di chiusura è presente solo dove è noto. Un riferimento viene raccolto da una posizione in un documento, e alcune posizioni dicono a quale tipo di entità puntano mentre altre no. Il campo è riportato dove il punto del riferimento ne ha registrato uno e omesso dove non l’ha fatto, anziché dedotto dalla forma del nome. È riportato come la parola che un autore scrive in testa a un documento, che è la stessa parola che ogni superficie che riporta una chiusura usa per la stessa voce.

La stessa parola chiede lo stesso documento altrove. aggrega inspect <release> --closure risponde a questa domanda dalla riga di comando, e la modalità release dello strumento describe vi risponde tramite il protocollo degli strumenti dell’assistente. Tutti e tre eseguono un’unica risoluzione sulla Release, quindi non possono arrivare a dissentire su ciò da cui dipende una Release. Vedi aggrega inspect, «La chiusura delle dipendenze».

Modello della cache

Le operazioni sono guidate dalla cache: chiama aggrega/validate per un file prima di hover / completion / resolve / diagnostics su di esso. Quella chiamata di inizializzazione non ha bisogno di una Release — una validazione che non ne indica nessuna analizza comunque il buffer e popola la cache — quindi queste operazioni funzionano in un workspace che non ha alcuna Release da indicare. La cache di parsing viene confrontata con l’ora di modifica su disco di ogni file a ogni lettura, quindi le modifiche esterne (un salvataggio dell’editor, un git checkout) vengono rilevate automaticamente — l’aggrega/invalidate dell’editor è un’ottimizzazione, non un requisito di correttezza.

La cache appartiene al workspace che l’ha inizializzata. Un file validato in un workspace è memorizzato in cache per quel workspace, quindi lo stesso percorso interrogato in un altro viene segnalato come non ancora validato anziché ricevere una risposta dalla voce del primo. È questo che impedisce a una domanda su un secondo workspace di rispondere in modo errato o di costare al primo il suo stato già caldo — e anche aggrega/invalidate svuota solo il workspace che indica.

Chiedere le diagnostiche mentre è in corso una validazione

Una validazione inizializza due cose su un file — il parsing che consegna alle altre operazioni e le constatazioni che riporta — e le inizializza a un momento di distanza. aggrega/diagnostics è l’unica richiesta che le legge entrambe: ha bisogno del parsing per sapere che il file è uno su cui può rispondere, e risponde a partire dalle constatazioni. Quindi una richiesta che arrivasse tra quei due momenti deciderebbe di poter rispondere quando non c’è ancora nulla con cui rispondere.

Invece aspetta. Invia aggrega/diagnostics per un file che è in fase di validazione in questo momento e la risposta arriva quando quella validazione termina, con ciò che ha trovato. C’è una sola risposta corretta per il file qualunque sia la tempistica, ed è la risposta che ottieni — non è mai una lista vuota per un file la cui validazione sta per riportare errori, che è l’unica risposta sbagliata da cui un client non può riprendersi, perché nulla ti spinge a chiedere di nuovo di un file che ti è stato detto essere pulito. Le altre operazioni basate sulla posizione — hover, completion, resolve, findReferences, findImplementations — leggono il parsing e rispondono a partire dal parsing, quindi non hanno nulla da aspettare e non aspettano mai.

Due cose terminano l’attesa in anticipo, ed entrambe le hai già. $/cancelRequest per l’id di quella richiesta la interrompe, e un aggrega/shutdown cooperativo la interrompe. Nessuna delle due richiede nulla in più sulla richiesta.

E l’attesa è limitata. Se la validazione non è terminata entro il budget che il daemon le concede, la richiesta viene rifiutata con il codice validation-in-flight anziché ricevere una risposta vuota — vedi Codici di errore. Quel rifiuto significa che il lavoro che stai aspettando è davvero in corso, quindi la cosa da fare è chiedere di nuovo a breve; non è un segnale per inviare un’altra validazione, che aggiungerebbe lavoro e non risponderebbe a nulla.

Un daemon che esegue le richieste una alla volta risponde nell’ordine di arrivo, quindi nulla si sovrappone e nessuna attesa avviene mai. Un daemon che le esegue in modo concorrente risponde alle stesse domande nello stesso modo, ed è l’attesa a renderlo vero: la risposta che ottieni è quella che ti avrebbe dato un ordinamento seriale.

Dimensioni in una risposta

Una risposta che riporta una quantità in byte la riporta due volte: come numero e come la stessa quantità scritta per esteso. Il campo scritto è il nome del campo numerico con Text aggiunto in fondo — size e sizeText, totalSize e totalSizeText, reclaimedBytes e reclaimedBytesText, e così via in ogni risposta che riporta una dimensione.

Mostra la forma scritta e calcola con il numero. Lo scopo di inviarle entrambe è che un client non debba mai formulare da sé una dimensione: il daemon la scrive con lo stesso formattatore usato dalla riga di comando, quindi aggrega cache status e aggrega/cacheStatus mostrano una data cache in modo identico, fino all’arrotondamento. Un client che componesse il proprio testo se ne discosterebbe la prima volta che fosse in disaccordo su una soglia.

La forma scritta usa unità binarie — 512 B, 1.0 KiB, 5.0 MiB, 3.0 GiB — che è lo stesso vocabolario che aggrega/cacheEvict accetta in maxSize, quindi una dimensione letta da una risposta può essere rinviata nella richiesta successiva senza essere riscritta. Oltre i byte il testo riporta una cifra decimale, così indica la quantità come un lettore vuole vederla anziché al byte; quando ti serve il conteggio esatto, è a questo che serve il campo numerico.

Dove il numero è facoltativo lo è anche il testo, e i due non sono mai presenti a metà: la dimensione del plugin in una risposta di pubblicazione riporta pluginSize e pluginSizeText insieme oppure nessuno dei due.

Ogni richiesta indica il workspace a cui si riferisce

Invia workspaceRoot in ogni richiesta: il percorso assoluto della radice del workspace su cui agisce quella richiesta. Il daemon non possiede alcun workspace proprio e non ne ricorda nessuno tra una richiesta e l’altra, quindi ciò su cui una richiesta riceve risposta è il workspace che ha indicato e nient’altro. Due richieste che indicano due workspace ottengono due risposte, e nessuna delle due può vedere le entità, le Releases, i parsing in cache o le diagnostiche dell’altra.

Una richiesta che non ne indica nessuno viene rifiutata con l’errore standard invalid-params che indica il parametro, e così anche un valore vuoto, che non dichiara alcun workspace e viene trattato come un valore mancante. Altre due forme vengono rifiutate per lo stesso motivo, ciascuna indicata nel messaggio: un percorso relativo, perché una radice del workspace non ha nulla rispetto a cui essere relativa; e un percorso che non è una directory esistente, perché un workspace è un albero.

Tre richieste non hanno bisogno di workspaceRoot, e ciascuna perché il suo oggetto non è un workspace. aggrega/getSchema e aggrega/scaffoldEntity rispondono a partire dagli schemi compilati nel binario in esecuzione, quindi un workspace non contribuisce nulla a nessuna delle due — ed è ciò che permette a entrambe di rispondere in una directory che nessuno ha preparato. aggrega/initialize è la terza, ed è dove dichiari un workspace anziché agire su uno. L’altra forma di aggrega/scaffoldEntity, che scrive o elenca gli esempi eseguibili della documentazione, agisce invece su un workspace, e una richiesta per essa ne indica uno come qualsiasi altra.

Lo stato in cache di ogni workspace è conservato separatamente, e indicarne un secondo non costa nulla al primo. L’indice del catalogo, la cache di parsing e le diagnostiche di un workspace appartengono a quel workspace, quindi una domanda posta su un altro punto non rimuove ciò che un editor ha accumulato per la cartella che qualcuno ha aperto. Due grafie di una stessa radice sono un unico workspace, quindi un percorso che contiene un . interno o un separatore doppio raggiunge lo stesso stato caldo della sua forma semplice.

Dichiarare il workspace per cui vuoi ricevere le diagnostiche in push

Le diagnostiche viaggiano in due modi: le chiedi tu, oppure il daemon te le invia in push. Il daemon invia in push solo per il workspace che hai dichiarato all’handshake. Ogni altra richiesta risponde con le sue constatazioni nella propria risposta e non invia nulla in push.

Dichiaralo inviando workspaceRoot in aggrega/initialize. È tutto ciò che fa la dichiarazione — non fa da ancoraggio a nulla, e nessuna richiesta successiva riceve risposta in base a essa.

Il motivo per limitarlo è lo scopo di una diagnostica inviata in push. Il push è ciò che mantiene aggiornato l’elenco dei problemi di un editor mentre qualcuno digita, ed è esattamente la cosa sbagliata da fare con una risposta che nessuno ha chiesto di vedere: senza la regola, una domanda posta su un secondo workspace — da un altro strumento che condivide il daemon, per esempio — riempirebbe l’elenco dei problemi di un lettore con constatazioni su file che non ha mai aperto. Limitare il push tiene la domanda di un chiamante fuori dall’elenco dei problemi di un altro chiamante.

Il campo è facoltativo, e le tre cose che puoi intendere con esso sono distinguibili:

ciò che inviidove vanno i pushciò che riporta l’handshake
nullail workspace su cui è stato avviato il processoquel workspace
una radice del workspacequel workspacequel workspace
la stringa vuotada nessuna parte — nessuna diagnostica viene mai inviata in pushuna radice vuota

Non inviare nulla lascia i push sul workspace su cui è stato avviato il processo, quindi un client che non dichiara nulla riceve le diagnostiche per quel workspace. Inviare la stringa vuota è la dichiarazione onesta per un chiamante che non è un editor e non ha alcun elenco dei problemi da mantenere sincronizzato: ogni constatazione gli arriva comunque, nella risposta alla richiesta che l’ha prodotta.

Un workspace dichiarato viene risolto esattamente come uno indicato da una richiesta, quindi una dichiarazione che indica un percorso relativo, o un percorso che non è una directory, viene rifiutata all’handshake anziché lasciare i push diretti verso un punto inatteso.

Radice del workspace e Release attiva

Il daemon risolve ciascun workspace nominato da una richiesta nello stesso modo in cui lo risolve ogni comando aggrega, e Configurazione riporta che cosa fa da ancora a una radice e in quale ordine. Due conseguenze contano per un client. Un .aggrega-config.yaml senza un blocco workspace: non fa da ancora: contribuisce comunque le sue impostazioni, ma un semplice file di impostazioni non può trasformare ogni directory superiore in una radice di workspace. E quando nulla fa da ancora, si usa la directory di lavoro — il daemon si avvia e le operazioni semplicemente non risolvono nulla, invece di rifiutarsi di funzionare.

Anche il processo viene avviato su un workspace, da --workspace-root o risalendo dalla sua directory di lavoro, e quella risoluzione fa due cose e nessun’altra: dimensiona il pool di worker, che è una proprietà del processo e non di una richiesta, ed è la dichiarazione predefinita per le diagnostiche inviate dal daemon. Nessuna richiesta riceve risposta in base a essa.

Anche la configurazione è la stessa cascata che legge ogni comando, e Configurazione è dove viene descritta. Ciò che il daemon aggiunge è solo che la lettura che ne fa ciascun workspace viene eseguita una volta, quando quel workspace viene nominato per la prima volta, e riutilizzata per ogni richiesta successiva che lo riguarda. Un file di configurazione che quella cascata leggerebbe e che è un collegamento che porta fuori dal workspace — il .aggrega-config.yaml del workspace stesso, o l’overlay di proprietà della CI accanto a esso — non viene letto, qui come in un terminale, e nient’altro di ciò che quel file avrebbe configurato viene letto al suo posto. Ciò che differisce da un terminale è ciò che risponde comunque. Il daemon avviato su un tale workspace si avvia, e lo segnala una volta sul suo flusso di errore; una richiesta che ne nomina uno riceve in ogni caso la risposta seguente. aggrega/releaseCandidates e aggrega/catalogIndex — le due richieste che elencano ciò che un workspace contiene — rispondono, leggendolo senza nulla di configurato: i documenti del workspace stesso vengono elencati, nessuna directory di catalogo viene letta e il file trattenuto viene nominato in unreadLinkedFiles, che la ricerca lo abbia incontrato o no. Quel nome è il modo in cui un client capisce che la configurazione del workspace porta fuori da esso. Ogni altra richiesta che nomina il workspace — una build, un grafo, una validazione, la Release predefinita, la configurazione effettiva, una scrittura e aggrega/catalogIndex nei termini di una Release — è decisa da quella configurazione, quindi viene rifiutata con l’errore invalid-params che riporta E0321 — read-leads-out-of-workspace nel data dell’errore — e la frase che nomina il collegamento e dove porta. Anche l’handshake risponde per un tale workspace, riportando defaults come suo configSource, poiché nessun file di configurazione ha contribuito a ciò con cui rispondono gli elenchi. Rimuovi il collegamento, o fallo puntare a un file dentro il workspace, e la richiesta successiva legge la configurazione. Sotto i file del progetto si trova il livello globale: il file che --config nomina sulla riga di comando che ha avviato il daemon, per ogni workspace che serve; altrimenti il file nominato dalla variabile d’ambiente AGGREGA_CONFIG quando è impostata; e altrimenti la posizione predefinita — su Windows aggrega\config.yaml dentro la directory nominata dalla variabile d’ambiente APPDATA, e altrove aggrega/config.yaml dentro la directory nominata da XDG_CONFIG_HOME, con ripiego su ~/.config/aggrega/config.yaml — caricato quando presente. Sotto di esso si trovano i valori predefiniti incorporati.

Le operazioni che agiscono su una Release ne ricevono una come parametro; il daemon non ne seleziona alcuna di propria iniziativa. Un workspace dichiara comunque a quale Release punta, e una cascata in quattro passi legge quella dichiarazione: il campo di configurazione build.authoring_release, poi un file marcatore .aggrega/active-release, poi un’euristica per una singola Release nel workspace, poi un ripiego basato solo sull’Aggregate. Un marcatore che scrivi ha quindi la precedenza sull’euristica, e un marcatore che nomina una Release che non può essere caricata ricade sull’euristica anziché sul ripiego. Un marcatore che nomina una Release fuori dal workspace — tramite un percorso assoluto, un percorso che risale oltre la radice o un collegamento che porta fuori da essa — non viene letto, a meno che la configurazione del tuo workspace non nomini quella Release come build.authoring_release o come chiave di workspace.releases: la configurazione è il modo per raggiungere una Release tenuta fuori dal workspace, il marcatore no. La cascata allora prosegue esattamente come fa per un marcatore che non riesce a caricare, e dove non approda a nulla, trace dice perché nella riga del marcatore e reason nella sua frase sul marcatore.

aggrega/activeRelease riporta ciò che quella cascata sceglie, ed è un suggerimento per un client più che un’impostazione su cui il daemon agisce. Chiedi al daemon invece di leggere tu stesso gli input della cascata: il campo di configurazione e il file marcatore sono due dei quattro input, quindi qualunque dei due tu legga indica la scelta del workspace solo quando è proprio l’input che ha prevalso. Un marcatore che nomina una Release che non può essere caricata è il caso più chiaro — la cascata sceglie una Release del tutto diversa, e chi leggesse il marcatore riporterebbe quella che ha fallito.

La cascata viene eseguita quando lo chiedi e non prima, il che ha due conseguenze su cui vale la pena fare affidamento. L’handshake resta veloce qualunque sia la dimensione dell’albero, perché non attende la scansione del workspace. E la risposta segue il workspace: scrivi un marcatore — con aggrega/setActiveRelease, che risponde con la nuova scelta stessa — modifica la configurazione, aggiungi o rimuovi un file di Release, poi chiedi di nuovo, e ottieni la nuova risposta dallo stesso daemon. Cambiare la Release su cui lavori non richiede mai di riavviare il daemon — un client invia un release diverso nella sua richiesta successiva.

Le operazioni che cercano nell’intero workspace anziché in un solo buffer — completion, hover, resolve, findReferences e findImplementations — enumerano lo YAML sotto la radice del workspace, e quell’enumerazione rispetta .gitignore. Ogni .gitignore dalla radice del workspace fino alla directory del file stesso contribuisce, e prevale il più vicino, quindi un file YAML che il tuo repository ignora non viene offerto come candidato di completamento e non viene riportato come definizione o riferimento. Un .gitignore che è un collegamento che porta fuori dal workspace non viene letto, quindi un file altrove sulla macchina non decide mai quali documenti del workspace vengono cercati. Gli alberi vendorizzati e l’output generato restano quindi fuori dai risultati tra file senza alcuna impostazione di esclusione separata da mantenere — e un documento che ti aspetti venga trovato ma che hai ignorato non comparirà, che è l’unico caso da verificare quando un riferimento sembra mancare. I Components e le Features che completion offre anche dalle tue catalog_dirs configurate sono una lettura diversa: provengono da quelle directory così come configurate — le stesse directory che legge una build di una Release quando la configurazione non le assegna directory proprie, oppure, per una richiesta che nomina una Release, quelle di quella Release — quindi le entità di una directory di catalogo vengono offerte che un .gitignore la copra o no — tranne un’entità dietro un collegamento che porta fuori dalla directory entro cui devono restare le letture di una directory di catalogo, che non viene letta né offerta.

Una richiesta che nomina una Release legge le directory di catalogo di quella Release, che sono quelle che legge una sua build in un terminale: le sue, dove la configurazione del workspace gliene assegna sotto workspace.releases, e altrimenti le catalog_dirs del workspace. Ciò riguarda aggrega/build, aggrega/buildPreview, aggrega/irGraph, aggrega/releaseClosure, aggrega/resolveDependencies, aggrega/validate e aggrega/lint che nominano una Release, aggrega/attachCandidates e aggrega/attachmentContainer indirizzate a un nodo del grafo di una Release, e aggrega/connectionAtPosition, oltre alle richieste elencate nella sezione successiva quando ne nominano una. Così una sola sessione risponde per ogni Release di un workspace che tiene una variante del catalogo per Release, ciascuna dalla propria variante, senza inviare nulla oltre al percorso della Release. Una richiesta che non riguarda una singola Release — aggrega/catalogIndex, aggrega/entityDefinition, completion, hover e resolve che non nominano alcuna Release, e aggrega/attachCandidates indirizzata a un’entità o a un insieme di etichette — legge le catalog_dirs del workspace. aggrega/lint che non nomina né un’entità né una Release è l’eccezione in un workspace che nomina Releases sotto workspace.releases: lì controlla l’intero catalogo una volta per ciascuna Release, ogni passata sulle directory di quella Release, come descrive Pubblicare le convenzioni, su richiesta e a ogni modifica. Vedi Assegnare a una Release le proprie directory di catalogo.

Rispondere nei termini di una Release

aggrega/catalogIndex, aggrega/entityDefinition e le cinque richieste che partono da un cursore — aggrega/hover, aggrega/resolve, aggrega/completion, aggrega/findReferences e aggrega/findImplementations — non riguardano una singola Release, e ciascuna accetta un release facoltativo che le fa riguardare una Release. È un percorso relativo alla radice del workspace, soggetto allo stesso contratto a cui lo sottopongono le altre richieste che accettano una Release; un valore che non nomina alcun file di Release, o che nomina una directory, viene rifiutato anziché ricevere una risposta nei termini del workspace pur sembrando nei termini della Release.

Ciò che una Release raggiunge, per ogni richiesta qui: i documenti del workspace sotto le directory di catalogo che il suo stack legge, e ogni documento del workspace che non si trova sotto alcuna directory di catalogo — una Release, il suo Aggregate e il suo Manifest scritti accanto ai cataloghi. Un documento del workspace sotto una directory di catalogo letta solo da altre Releases non fa parte della sua risposta: non elencato, non risolto, non offerto. È ciò che impedisce di confondere varianti di una stessa entità, tenute una accanto all’altra per Releases diverse.

  • L’elenco. Nominare una Release elenca le entità che quella Release vede. Le Features elencate sono quelle dichiarate dalle directory di catalogo di quella Release, e un documento del workspace sotto una directory di catalogo letta solo da altre Releases viene escluso — così un workspace che tiene una variante di un’entità per Release elenca l’unica variante con cui quella Release viene compilata, anziché tutte le varianti una accanto all’altra. Un documento che non si trova sotto alcuna directory di catalogo, come una Release, il suo Aggregate e il suo Manifest scritti accanto ai cataloghi, appartiene all’elenco di ogni Release.
  • Una ricerca per nome. Nominando una Release, il nome viene risolto attraverso le directory di catalogo di quella Release, quindi un nome dichiarato da più varianti si risolve nella variante con cui quella Release viene compilata. Un nome che le sue directory non risolvono viene rifiutato con una spiegazione che nomina la voce di quella Release sotto workspace.releases, poiché è quella voce che la ricerca ha letto. Un riferimento a un registry non accetta una Release, e viene rifiutato se ne riceve una: viene letto dal registry che lo pubblica, qualunque Release sia nominata.
  • Hover e vai alla definizione. Nominando una Release, il riferimento sotto il cursore viene prima risolto attraverso le directory di catalogo di quella Release, nell’ordine indicato dalla configurazione del workspace — la stessa risoluzione eseguita da una ricerca per nome nei termini di quella Release — quindi l’entità mostrata, e il documento aperto, è la variante in cui quelle directory lo risolvono, anche dove un documento del workspace altrove dichiara lo stesso nome. Solo dove nessun documento sotto quelle directory risponde per esso vengono cercati i documenti del workspace che quella Release raggiunge. Senza nominarne alcuna, l’ordine è inverso: i documenti del workspace vengono cercati per primi, quindi un riferimento a cui risponde un documento del workspace mantiene quella risposta, e le catalog_dirs del workspace vengono consultate solo dove nessun documento dichiara il nome — ed è ciò che trova un’entità contenuta solo in una directory di catalogo configurata, inclusa una fuori dall’albero del workspace. Dove l’editor tiene una copia non salvata del documento in cui si risolvono le directory di una Release, e quella copia dichiara ancora il nome, la risposta viene letta dalla copia, quindi una posizione cade sulla riga che l’editor mostra.
  • Completamento. Nominando una Release, i nomi offerti sono quelli dichiarati dai documenti del workspace che quella Release raggiunge, insieme ai Components e alle Features dichiarati dalle directory di catalogo di quella Release.
  • Riferimenti e implementazioni. Nominando una Release, una posizione in un documento del workspace che quella Release non raggiunge non viene riportata, quindi una variante tenuta per un’altra Release non viene mai elencata come riferimento o implementazione di questa.
  • Che cosa può agganciarsi a un nodo del grafo. aggrega/attachCandidates indirizzata a un nodo del grafo di una Release è sempre nei termini di quella Release — vedi Che cosa ti dice una risposta sui candidati all’aggancio.

Senza nominarne alcuna, la risposta si basa sulle directory di catalogo del workspace stesso, come descrive il paragrafo precedente.

Raggiungere un registry, e scrivere

La maggior parte delle richieste qui risponde dal workspace e da ciò che è già in cache, e non scrive nulla. Alcune, nominate, fanno di più, e si dividono lungo due assi indipendenti: che cosa una richiesta raggiunge, e fin dove arriva ciò che modifica.

Le richieste che si rivolgono a un registry si dividono in quelle che leggono e quelle che pubblicano. aggrega/resolveDependencies recupera ciò di cui una Release ha bisogno, e aggrega/build vi si aggiunge quando — e solo quando — il suo campo autoPull le chiede di risolvere prima le dipendenze, nel qual caso raggiunge un registry e scrive il lockfile prima di eseguire il rendering; aggrega/registryUpdate percorre ogni registry configurato per ricostruire l’indice di ricerca locale; aggrega/pluginAdd cerca nel registry configurato il plugin che una richiesta nomina e ne legge le versioni pubblicate per fissarne una; aggrega/registryAdd chiede al registry che registra la politica di fiducia che quel registry pubblicizza, a meno che la richiesta non rinunci al recupero o fornisca una politica propria, e aggrega/configInit chiede lo stesso al registry che sta inizializzando; aggrega/explainError acquisisce il bundle di documentazione da cui legge la spiegazione dettagliata di una condizione, una volta, dove la cache condivisa da ogni progetto sulla macchina non contiene alcuna copia ammessa dal controllo di firma del workspace stesso — vedi aggrega explain; aggrega/scaffoldEntity inviato con example o list acquisisce lo stesso bundle alle stesse condizioni, e una scrittura scrive poi l’esempio in una nuova directory del workspace; aggrega/import recupera un importer core dal registry predefinito del workspace, una volta, dove la macchina non lo possiede ancora, e, in un workspace che non indica alcuna cartella di catalogo, l’istantanea pubblicata del catalogo che legge — vedi Che cosa ti dice una risposta di importazione; e aggrega/entityDefinition legge l’entità nominata da un riferimento a un registry quando ne viene inviato uno come suo name, senza scrivere nulla. aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts e aggrega/deprecateArtifact scrivono su un registry — byte, una firma o un marcatore di ritiro. Una richiesta raggiunge un registry solo quando è stata inviata per farlo: un elenco riporta ciò che la configurazione fissa, una ricerca legge un’istantanea offline, e una pubblicazione richiesta con dryRun calcola ciò che invierebbe e non contatta nessuno.

La regola riguarda quando un’operazione viene eseguita, non quale superficie la esegue. Un’operazione che recupera o scrive viene eseguita perché una richiesta l’ha nominata, e mai come effetto collaterale della validazione di un documento, dell’ispezione di un grafo o dell’elenco delle entità di un workspace. Così un editor che valida a ogni battuta non raggiunge alcuna rete e non riscrive alcun lockfile, mentre un’azione «risolvi dipendenze» su cui l’utente fa clic fa esattamente ciò che fa aggrega pull — la stessa risoluzione, dietro entrambe le superfici, che scrive un lockfile identico byte per byte e riempie la stessa cache degli artefatti.

Non viene richiesto nulla. Nessuno osserva questo flusso, quindi l’identità viene risolta da una fonte di credenziali fornita o presente nell’ambiente, e mai chiedendo. Dove il comando da terminale avrebbe posto una domanda a una persona — un registry che richiede credenziali, una capacità servita da più di un plugin provider, il testo che un ritiro deve riportare — la richiesta fallisce con un messaggio che nomina che cosa fornire, invece di bloccarsi in attesa di una risposta che non arriverà mai. Un rifiuto lascia il workspace esattamente com’era: nessun lockfile viene scritto e nessun record parziale viene lasciato, e una pubblicazione che non è riuscita a risolvere una credenziale si rifiuta prima che qualunque byte raggiunga il registry.

Alcune modifiche vanno oltre questo workspace, e la risposta dice quali

Una richiesta nomina un workspace, quindi una risposta che non ha nulla da dire sulla propria portata si legge come relativa a quel workspace. Per diverse di queste richieste quella lettura sarebbe sbagliata, quindi ciascuna riporta la propria portata e un client dovrebbe mostrarla prima di agire sul risultato.

Pubblicare, firmare e ritirare vanno del tutto oltre la macchina, che è la portata più ampia di qualunque cosa qui. Le altre scritture qui sotto cambiano ciò che questa macchina risolve; queste cambiano ciò che fa chiunque risolva da quel registry. I byte pubblicati sono ciò che ottiene ogni consumatore di quel registry, e ripubblicare un contenuto diverso su un tag viene rifiutato anziché offerto, quindi nessuna richiesta qui ritira una pubblicazione — la risposta è pubblicare una nuova versione. Una firma e un marcatore di ritiro vengono allegati come elementi affiancati all’artefatto anziché sostituirlo, quindi i byte stessi restano intatti; ma chiunque recuperi l’artefatto in seguito recupera anche quelli, e nessuno dei due può essere richiamato da chi lo ha già. Il ritiro è il più facile dei tre da fraintendere: la versione resta recuperabile, mentre una retrazione di cui un workspace si fida la esclude da ciò che una risoluzione lì sceglierà.

La firma usa credenziali, e da dove provengono è bene saperlo prima di collegare un client. La firma keyless risolve un token di identità, nell’ordine, da identityToken nella richiesta, poi da AGGREGA_IDENTITY_TOKEN nell’ambiente del daemon, poi dall’endpoint OIDC di GitHub Actions presente nell’ambiente dove ne è raggiungibile uno, poi da SIGSTORE_ID_TOKEN. Quando nessuno di questi fornisce un token l’operazione si rifiuta e nomina che cosa inviare; non apre mai un browser, perché non c’è nessuno a guardarlo. La firma con chiave è l’alternativa offline, e una richiesta non nomina alcun percorso di chiave: ciò che una richiesta legge si trova dentro il workspace che ha nominato, e una chiave privata non viene mai tenuta dentro un workspace, quindi la chiave proviene invece dal blocco signing: della configurazione di quel workspace. Vedi aggrega sign per le due modalità di firma e che cosa contatta ciascuna.

Ognuna delle quattro risposte riporta reach, che contiene registries — ogni host di registry a cui la chiamata si è rivolta, ciascuno nominato una volta, nell’ordine in cui la chiamata vi si è rivolta per la prima volta, quindi un batch di firma o un file batch i cui riferimenti abbracciano più registry li nomina tutti — e beyondThisMachine, che è derivato da ciò che la chiamata ha effettivamente allegato anziché da ciò che ha chiesto: vero esattamente quando ha caricato contenuto o allegato una firma, una data di pubblicazione o un marcatore di deprecazione, e falso per un dry run e per una chiamata che ha trovato già presente tutto ciò che avrebbe allegato — una pubblicazione eseguita di nuovo su una versione già completa, o un batch di firma in cui ogni riferimento aveva già una firma che si verifica. Un dry run nomina comunque la destinazione a cui si sarebbe rivolto. Mostrala prima di agire sul risultato.

Registrare o rimuovere un registry scrive la configurazione condivisa tra tutti i workspace della macchina, per impostazione predefinita. Un registry e le identità di cui ti fidi su di esso sono di solito gli stessi ovunque lavori, quindi è lì che va la voce, a meno che la richiesta non invii workspace: true. Vale la pena dire chiaramente la conseguenza: aggrega/registryAdd e aggrega/registryRemove cambiano ciò attraverso cui risolve ogni progetto su quella macchina, compresi progetti che nessuno in questa sessione ha nominato. Entrambe le risposte riportano scope, con il configFile che è stato scritto e machineWide che dice se è quello condiviso. La rimozione è la più delicata delle due, perché aggiungere di nuovo non è lo stesso atto — la politica di fiducia che era fissata è scomparsa, e una registrazione successiva fissa ciò che il registry pubblicizza in quel momento.

Inizializzare una configurazione scrive per impostazione predefinita quello stesso file condiviso, e per la stessa ragione. aggrega/configInit registra un registry e la sua politica di fiducia, che sono strumenti a livello di macchina, quindi senza override scrive la configurazione attraverso cui risolve ogni progetto sulla macchina — e raggiunge quel registry una volta per leggere la politica che pubblicizza. La sua risposta riporta la stessa coppia scope dei due metodi del registry. Differisce da essi per un aspetto su cui vale la pena fare affidamento: si rifiuta anziché sovrascrivere un file di configurazione esistente, quindi non può sostituire una configurazione da cui qualcuno sta lavorando a meno che la richiesta non invii force. Congelare è il caso opposto: aggrega/configCapture non accetta alcun override, scrive sempre il file di configurazione del progetto stesso e non raggiunge alcun registry, quindi nulla di ciò che fa è visibile a un altro progetto. Vedi Che cosa lascia una scrittura della configurazione.

🔴 Aggiungere o rimuovere un plugin di estensione dei comandi scrive per impostazione predefinita quello stesso file condiviso, e questo è il caso da leggere con attenzione. aggrega/pluginAdd e aggrega/pluginRemove accettano un type, ed è il tipo a decidere dove va la scrittura quando non viene inviato alcun override. Una voce provider, governance, linter o importer dà forma alla build di un progetto, quindi va nella configurazione di quel progetto. Una voce cli è uno strumento a livello di macchina, quindi un’aggiunta di tipo cli che non nomina né global né workspace registra il comando nel file di configurazione globale attraverso cui risolve ogni workspace su questa macchina — il comando diventa un comando aggrega di primo livello per ogni progetto su quella macchina, compresi progetti che nessuno in questa sessione ha nominato, e ritirarlo è una rimozione separata anziché un annullamento. Invia workspace: true per mantenerlo locale. Entrambe le risposte riportano scope, con il configFile che è stato scritto e machineWide che dice se è quello condiviso, derivato dal file in cui la scrittura si è risolta. Un’aggiunta raggiunge anche il registry in cui ha cercato, quindi si trova su entrambi gli assi contemporaneamente. Vedi Che cosa ti dice una modifica di un plugin.

Le altre due richieste sui plugin scrivono solo dentro il workspace. aggrega/pluginSync scrive il file dell’entità Plugin che la richiesta nomina, e aggrega/pluginGenCatalog scrive le entità generate sotto l’outputDir che la richiesta nomina — entrambe dentro il workspace nominato dalla richiesta, entrambe rifiutando una destinazione assoluta o che si risolve fuori da esso, e nessuna delle due visibile a un altro progetto. aggrega/pluginGenCatalog legge il suo modulo e il suo overlay da dove li hai selezionati, il che non amplia dove scrive: i due sono risolti con regole diverse, quindi una generazione può leggere un modulo che hai compilato ovunque mentre le entità che produce finiscono comunque dentro il workspace. aggrega/pluginGenCatalog con dryRun non scrive nulla e restituisce invece il contenuto.

Anche fissare un’entità scrive solo dentro il workspace, e raggiunge gli host che le sue sorgenti nominano. aggrega/pin scrive l’entity.lock accanto all’entità che la richiesta nomina, che è un percorso dentro il workspace, e riempie la cache dei contenuti del workspace con le sorgenti che ha recuperato; nulla di ciò che scrive è visibile a un altro progetto. Si spinge all’esterno per risolvere ogni sorgente remota che l’entità nomina — un repository di chart, un host Git, un URL — che è la stessa portata che aggrega/resolveDependencies ha per le sorgenti che una Release consuma. aggrega/resolveDependencies e aggrega/publishEntity inviate con pinSources eseguono questo stesso passo, quindi ciascuna di esse scrive anche accanto alle entità che fissa; una pubblicazione che fissa raggiunge quindi il workspace oltre al registry. Una pubblicazione che non fissa non scrive nulla accanto all’entità, e raggiunge comunque quegli host: confrontare il lock con ciò che il passo registrerebbe significa recuperare ogni sorgente remota che l’entità scrive per esteso.

Installare la skill per l’assistente resta dentro il workspace a meno che la richiesta non invii global. aggrega/skillsInstall scrive la cartella di skill di progetto di ciascun assistente nominato dentro il workspace che la richiesta ha nominato, e nulla di ciò che vi scrive è visibile a un altro progetto; lo scope della sua risposta riporta machineWide false. Con global: true scrive invece la cartella per utente di ciascun assistente sotto la home directory, che quell’assistente legge in ogni progetto sulla macchina, e machineWide è true. In entrambi i casi non raggiunge alcun registry né alcuna rete.

Rimuovere una credenziale memorizzata ha una portata più ampia di qualunque altra cosa qui che si ferma a questa macchina. aggrega/logout modifica l’archivio delle credenziali, e quell’archivio è condiviso non solo da ogni progetto sulla macchina ma da ogni altro strumento che si autentica presso gli stessi registry — quindi una credenziale rimossa tramite una sessione sparisce per tutti, e aggrega/registryList la riporterà assente anche in ogni altro workspace. La sua risposta riporta scope con machineWide, che è sempre true: questo archivio non ha una forma limitata al workspace in cui risolversi, quindi non c’è alcun override da inviare né nulla a cui una richiesta possa aderire. scope volutamente non nomina alcun file, a differenza delle scritture della configurazione sopra. L’archivio delega a qualunque helper di credenziali o portachiavi del sistema operativo la macchina abbia configurato, quindi la rimozione è spesso servita da qualcosa che non è affatto un file, e nominare un percorso ti indicherebbe una posizione che la rimozione non ha necessariamente toccato.

La rimozione non è l’inverso dell’autenticazione, e un client non dovrebbe offrirla come tale. Questa superficie rimuove una credenziale e non ne acquisisce una: riavere una credenziale significa autenticarsi di nuovo con aggrega login in un terminale, perché memorizzarne una richiede un segreto digitato da una persona e nessuno osserva questo flusso. Quindi un «log out» offerto da un client è, da qui, a senso unico. Ciò che separa le due operazioni è se l’operazione deve ottenere qualcosa da chi la guida — una rimozione porta il suo unico valore nella richiesta, mentre l’acquisizione di una credenziale no — e non se è coinvolta una persona, dato che una persona ha scelto entrambe.

Recuperare spazio dal contenuto della cache va anch’esso oltre il workspace. Gli archivi dei moduli compilati e delle descrizioni dei plugin sono condivisi da ogni progetto sulla macchina, quindi aggrega/cachePrune, aggrega/cacheEvict e aggrega/cacheClear possono rimuovere contenuto da cui dipende un altro progetto. Ogni rimozione riporta il reach della classe da cui proviene, e ogni risposta riporta scope.machineWideClasses. aggrega/cacheStatus riporta la stessa portata su ogni classe anche se non cambia nulla, perché un client che decide se recuperare spazio ne ha bisogno prima di agire.

Aggiornare l’indice di ricerca è il caso opposto. aggrega/registryUpdate raggiunge ogni registry configurato, e ciò che scrive finisce sotto la directory di cache configurata di questo workspace — quindi non cambia nulla attraverso cui un altro progetto risolve. indexRoot nella risposta nomina quella directory.

Un aggiornamento parziale risponde anziché fallire. Una richiesta che nomina un registry il cui aggiornamento è fallito è un errore, perché non c’è alcuna risposta da dare. Una richiesta che aggiorna ogni registry configurato riesce anche dove alcuni di essi, o tutti, sono falliti: quelli aggiornati sono stati indicizzati e scritti, failed nomina gli altri, e ogni host riporta il proprio errore. Leggi failed anziché la presenza di un errore.

Se un registry è stato raggiunto è indicato da una chiave, non da un’interpretazione del messaggio. Un host che è fallito riporta unreachable: true dove il registry non è mai stato raggiunto — il suo nome non si è risolto, una connessione verso di esso è stata rifiutata o non è stato possibile aprirla, oppure non è stato possibile stabilire con esso una connessione sicura — e il rifiuto di una richiesta che nomina un registry riporta la stessa chiave nel suo data. Un registry che è stato raggiunto ed è fallito, con un elenco che si ripeteva o uno stato di errore, non riporta la chiave in nessuno dei due casi, e il suo error, o il messaggio del rifiuto, dice che cosa ha risposto. La chiave viene letta dal fallimento stesso, quindi non dipende da come il resolver di questa macchina formula un fallimento, e viene impostata solo dove il fallimento mostra che il registry non è mai stato raggiunto: un fallimento che non mostra nulla in un senso o nell’altro, come un limite di tempo scaduto senza traccia di quale passo abbia interrotto, viene riportato senza di essa. Indica un registry come non raggiunto in base alla chiave, e mostra l’errore come motivo.

La riga di comando riporta quella stessa scansione come un’uscita diversa da zero, e il tipo di lettore che sei decide quanto vale quell’uscita. Per una persona a un terminale non è il resoconto completo: aggrega registry update stampa quanti dei registry selezionati ha indicizzato, che cosa ha trovato ciascuno, quali non ha indicizzato e dove è stato scritto l’indice — quindi il riepilogo dice che cosa è successo e lo stato di uscita dice solo se è riuscito tutto. Per uno script è il resoconto completo, perché quel comando non offre alcuna modalità di output strutturato, quindi il suo stato di uscita è l’unico verdetto leggibile da una macchina disponibile. Ecco perché le due superfici rispondono diversamente alla stessa scansione parziale ed entrambe hanno ragione: questa consegna a un chiamante strutturato failed e riesce, mentre la riga di comando ha un solo bit da spendere e lo spende su «è stato mancato qualche registry».

Seguire un’operazione lunga

La maggior parte delle richieste qui risponde da ciò che è già su disco e risponde subito. Alcune svolgono prima un lavoro reale — risolvere le dipendenze di una Release, fissarne gli input esterni, pubblicare, firmare, ritirare — e il chiamante attende. Queste riportano ciò che stanno facendo mentre lo fanno, e lo si attiva esplicitamente per ogni richiesta.

L’attivazione richiede due passi, in quest’ordine.

  1. Dichiara la capacità all’handshake e attendi la risposta. Invia capabilities.window.workDoneProgress: true su aggrega/initialize. Non inviare nient’altro finché quella risposta non è arrivata: le richieste vengono servite in modo concorrente, quindi una richiesta scritta prima che l’handshake rispondesse può essere in esecuzione accanto all’handshake che doveva negoziare per essa. Ogni client deve già quell’ordinamento al protocollo; questa è un’altra cosa che dipende da esso.
  2. Metti un token nei params della richiesta. Aggiungi workDoneToken ai params della richiesta su cui vuoi ricevere aggiornamenti. Il valore lo scegli tu — una stringa o un numero — ed è ciò che lega le notifiche a quella chiamata. Generane uno nuovo per ogni chiamata.

La notifica. Ognuna è $/progress con params.token impostato al tuo token e params.value che porta un payload:

value.kindcontienequando
begintitle — che cosa sta accadendo, in una frase che puoi mettere davanti a un lettoreuna volta, quando il lavoro inizia
reportmessage — una riga del resoconto che l’operazione dà di séun numero qualsiasi di volte, man mano che l’operazione le scrive
endnulla oltre al tipouna volta, quando il lavoro è finito

Correla sul token, mai sull’id della richiesta. Una notifica non porta alcun id — non è una risposta a nulla — e il token è l’unica cosa in essa che rimanda alla tua chiamata. È voluto: in molti client l’id della richiesta appartiene al trasporto e non raggiunge mai il codice che ha emesso la chiamata, mentre il token è un valore che quel codice possiede già.

Un report porta il testo del compilatore stesso. Il messaggio è una riga che l’operazione ha scritto mentre lavorava, inoltrata con gli spazi circostanti rimossi e nient’altro modificato — non riformulata, non riassunta, non ricomposta — e una riga che l’operazione ha scritto vuota viene scartata anziché riportata come messaggio vuoto. Quindi un client mostra ciò che riceve così com’è. È la stessa proprietà che hanno le diagnostiche della risposta stessa: una condizione mantiene una sola formulazione per quante superfici la riportino.

Anche un passo su cui l’operazione resta in attesa è un report. Quando l’operazione entra in un passo su cui resta in attesa — la lettura di un registry, il recupero di un artefatto, la compilazione di un plugin — un report porta il nome del passo, con le parole che la riga di comando mostra accanto al suo indicatore di attesa per lo stesso passo. Vengono segnalati solo i passi in cui si entra tra il begin e l’end.

Una riga di output è un report. Un’operazione che scrive più righe insieme produce una notifica per riga, e una riga che l’operazione scrive a pezzi viene riportata una volta completa — quindi un messaggio non è mai mezza frase.

Non c’è alcuna frazione né percentuale, e non è un’omissione in attesa di essere colmata. Le operazioni che riportano qui lavorano su un insieme la cui dimensione non è nota quando il lavoro inizia — quanti riferimenti percorre una risoluzione, quanti layer carica una pubblicazione — quindi qualunque frazione sarebbe inventata. Disegna un indicatore indeterminato e mostra l’ultimo message.

I frame arrivano prima della risposta e mai dopo. Un begin arriva solo quando il lavoro è effettivamente iniziato, quindi una richiesta rifiutata per i suoi params — un percorso assoluto, un campo obbligatorio mancante — non produce alcuna notifica, solo il suo errore. L’end arriva prima della risposta, e l’esito dell’operazione è nella risposta anziché ripetuto nell’end.

Interrompere il lavoro è una notifica separata. Invia $/cancelRequest con l’id con cui hai inviato la richiesta. Il token non ha alcun ruolo nell’annullamento, e annullare non sopprime i frame già inviati.

Quali richieste riportano, e che cosa aspettarsi dalle altre

Riportano esattamente queste: aggrega/resolveDependencies, aggrega/pin, aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts, aggrega/deprecateArtifact.

Due cose valgono per ognuna di esse, ed entrambe sono il motivo per cui è nell’elenco: raggiunge un registry o un URL remoto per tuo conto, quindi quanto tempo impiega è determinato da qualcosa fuori dalla macchina; e scrive già il proprio resoconto di sé man mano che procede — il resoconto che legge una persona che osserva un terminale. Quindi la segnalazione ti consegna quello stesso resoconto anziché un secondo composto per la trasmissione, e nulla di ciò che l’operazione fa ha dovuto cambiare per produrlo.

Ogni altra richiesta accetta un token e non invia nulla. Inviarne uno è innocuo e non un errore: viene accettato, non arriva alcuna notifica, e la risposta è esattamente quella che avresti ottenuto senza. Quindi un client può allegare un token a ciò che vuole e semplicemente non disegnare nulla quando non arriva nulla.

🔴 Non interpretare il silenzio come «questa è istantanea». La maggior parte delle altre risponde davvero da ciò che è già su disco — una validazione, un hover, un completamento, un grafo, un elenco della cache, una lettura della configurazione — ma non tutte: aggiornare l’indice di un registry, aggiungere un plugin, un controllo prima della pubblicazione e la prima espansione di un codice su una macchina che non contiene documentazione che il workspace possa leggere raggiungono tutti un registry, e compilare una Release è lavoro reale. Queste impiegano il tempo che impiegano e oggi non riportano nulla. Mostra un indicatore indeterminato per ogni richiesta che sei disposto ad attendere, e tratta le notifiche come un dettaglio che ottieni quando è disponibile, non come ciò che ti dice che il lavoro è in corso.

Due rifiuti

Entrambi sono errori invalid-params ed entrambi dicono che cosa fare, perché un token che non facesse nulla in silenzio ti lascerebbe in attesa di un flusso che non sarebbe mai arrivato.

  • Un token da una sessione che non ha dichiarato alcuna capacità window.workDoneProgress viene rifiutato, nominando la capacità da dichiarare. Dichiarala all’handshake, oppure ometti il token.
  • Un token che non è né una stringa né un numero viene rifiutato, nominando le due forme. Un token assente, e un null esplicito, non sono rifiuti — entrambi significano che non hai chiesto alcun report.

Consapevolezza del lockfile

Il daemon controlla la deriva di un lockfile a ogni aggrega/irGraph, rispetto alla Release nominata da quella richiesta, segnalando la deriva come avviso non bloccante. L’avviso nomina il comando che riscrive quel lockfile con dentro la Release, scritto come la richiesta l’ha inviata — aggrega pull --release seguito dal release che hai inviato, che è come si scrive in un terminale nella radice del workspace. aggrega/irGraph richiede che sia presente un lockfile. Non c’è alcun controllo separato all’avvio: una richiesta dice di quale Release si tratta, quindi il verdetto viene calcolato per quella Release quando viene chiesto anziché una volta sola per una Release scelta in anticipo.

Un avviso di deriva sparisce quando sparisce il suo lockfile. L’avviso è pubblicato sul lockfile rispetto a cui è stato sollevato, e un lockfile che non c’è più non ha più pin che possano essere andati alla deriva — il comando che l’avviso nomina scriverebbe un nuovo file anziché riparare quello vecchio. Quindi ogni richiesta che trova il lockfile mancante ritira l’avviso prima di rifiutare con l’errore di lockfile assente: aggrega/irGraph, aggrega/releaseClosure, aggrega/build, aggrega/buildPreview, aggrega/attachCandidates e aggrega/attachmentContainer interrogate su un nodo del grafo, e aggrega/connectionAtPosition. Il ritiro arriva come notifica aggrega/publishDiagnostics per il lockfile con un elenco vuoto, prima del rifiuto. Proviene da qualunque di quelle richieste venga a sapere per prima della cancellazione, quindi un client che segnala la cancellazione e poi chiede qualunque cosa su quella Release vede l’avviso rimosso senza dover chiedere specificamente il grafo. Un lockfile ancora presente e ancora alla deriva mantiene il suo avviso attraverso ognuna di quelle richieste. aggrega/invalidate che nomina il lockfile scarta ciò che il daemon tiene per esso ma non invia nulla; è la richiesta successiva a informare il client. E un lockfile che il daemon non può nemmeno esaminare — uno la cui directory non può leggere, per esempio — non ritira nulla, perché potrebbe essere ancora lì e l’avviso potrebbe essere ancora vero.

Anche aggrega/build e aggrega/buildPreview ne richiedono uno, e vincolano la Release a esso anziché avvisare — eseguono il rendering con l’impostazione di una superficie che emette un artefatto, quindi un lockfile che non corrisponde più a ciò in cui la Release si risolve le arresta dove un’ispezione si limiterebbe ad avvisare. Una Release senza lockfile viene rifiutata con l’errore di lockfile assente. L’eccezione è una build il cui campo autoPull le chiede di risolvere prima le dipendenze: quella build scrive il lockfile e poi esegue il rendering rispetto a ciò che ha scritto, e un lockfile prodotto in quel modo non viene controllato per la deriva una seconda volta, perché la risoluzione che lo ha scritto ha eseguito lo stesso controllo su di esso prima di scriverlo e non scrive alcun lockfile che quel controllo rifiuta.

Un lockfile che esiste ma non registra alcun digest per un plugin non ferma il grafo — un lockfile assente sì. Sono due condizioni e solo la seconda comporta un rifiuto. aggrega/irGraph non vincola i byte che risolve ai loro digest registrati: un pin che non può verificare viene riportato anziché rifiutato, e il grafo viene disegnato con il risultato nel pannello Problems, poiché un editor che rifiuta di disegnare il grafo lascia il lettore senza nulla, dove un report gli lascia qualcosa su cui agire. Altrove il plugin viene eseguito comunque, con un avviso che dice che nulla ne ha controllato i byte. Ciò che aggrega/irGraph rifiuta è il lockfile mancante: si ferma prima di risolvere qualunque cosa e risponde con l’errore di lockfile assente, nominando il lockfile che ha cercato e la Release, così un client può offrire direttamente aggrega pull --release <release> — oppure inviare aggrega/resolveDependencies per quella Release e scrivere il lockfile senza lasciare la sessione. Tenere separate le due cose è importante, perché un grafo disegnato è un’immagine su cui poi un lettore ragiona, e uno costruito da byte che nulla ha controllato viene disegnato esattamente come uno controllato, con il risultato in un punto dove il lettore non sta guardando. Quindi un grafo non è un verdetto sui byte che lo sostengono — aggrega/build e aggrega/buildPreview sono le superfici che vincolano una Release ai suoi digest registrati, arrestandosi dove l’ispezione si limita a riportare.

aggrega/validate, quando una richiesta nomina una Release, legge il lockfile di quella Release solo per i suoi pin e i suoi avvisi di deprecazione — e non ne legge alcuno per un’entità di catalogo che controlla come singola entità, così come la riga di comando non ne legge alcuno. Non vincola i plugin che esegue ai digest registrati, e non ricostruisce dal lockfile l’insieme di attachment dei plugin di trasformazione — valida rispetto alla configurazione del workspace così come si presenta davanti a te, che è ciò che un editor deve fare mentre stai modificando quella configurazione. aggrega validate e aggrega build fanno entrambe le cose, e restano le superfici autorevoli per un verdetto su un workspace di cui è stato fatto il commit.

Le sue notifiche di deprecazione coprono entrambi i luoghi in cui è registrato un ritiro. Un marcatore su un riferimento fissato si trova nel lockfile; un marcatore su un plugin associato in un ruolo che restituisce un verdetto di accettazione o rifiuto — un’associazione plugins.governance a ir-verdict o render-verdict, o un’associazione plugins.linter — si trova nel record di fiducia dei plugin accanto a esso, quindi la validazione legge entrambi e indica ogni riferimento ritirato e ogni plugin ritirato come un avvertimento all’inizio dell’Aggregate, con le parole che stampa aggrega build. Una notifica non cambia alcun verdetto. Un record di fiducia presente che non può essere letto viene segnalato come errore al posto della validazione, anziché essere letto come uno che non registra nulla. aggrega/releaseClosure riporta lo stesso insieme nel suo deprecations.

Dove si trova il lockfile di una Release

Ogni risposta che nomina una Release ne nomina anche il lockfile, così un client non deve mai ricavarne il percorso. aggrega/activeRelease lo riporta come lockfile accanto a release, aggrega/releaseCandidates come la mappa lockfiles accanto a releases, e l’errore di lockfile assente come lockfile nel suo data. Ciascuno è il file che aggrega pull --release <release> scrive e aggrega build legge, e il file che ogni richiesta sopra cerca — quindi un client che osserva il lockfile di una Release, per accorgersi che viene scritto, riscritto o cancellato, osserva il file che il daemon intende. Il lockfile si trova accanto alla sua Release e prende il nome della Release con un’estensione .yaml o .yml sostituita da .lock; una Release nominata con qualunque altra estensione mantiene il suo nome intero, quindi il lockfile di release.rel è release.rel.lock. Leggi il percorso dalla risposta anziché comporlo da quella descrizione, e i due non potranno divergere.

I riferimenti esterni richiesti da un rendering

Un rendering può richiedere contenuti da un URL remoto — ad esempio lo schema dei valori di un chart con un riferimento remoto. Gli input esterni sono congelati per ogni rendering che questo daemon esegue in risposta a una richiesta che chiedeva soltanto di essere informata di qualcosa. Un riferimento che il lockfile della Release fissa viene servito dallo store indirizzato per contenuto, il che è una lettura di contenuti già presenti su disco anziché un download, e viene confrontato con ciò che il lockfile registra prima che i suoi byte vengano serviti — così un rendering qui vede ciò che vede una build e solleva gli avvisi che una build solleva. Un riferimento che il lockfile non fissa viene rifiutato anziché scaricato: acquisirlo significherebbe raggiungere una rete e scrivere un blob nello store, e una sessione non fa né l’una né l’altra cosa per una richiesta che chiedeva soltanto di essere informata di qualcosa. È la regola descritta in Raggiungere un registry e scrivere letta dal lato del rendering, e vale in qualunque modo si sia arrivati a quel rendering.

La richiesta che esiste per fissare è l’eccezione, ed è la stessa eccezione che la regola del registry già prevede. A aggrega/resolveDependencies viene chiesto di acquisire, quindi il rendering che esegue per scoprire quali riferimenti questa Release consuma raggiunge la rete e scrive ciò che fissa — ed è questo che rende il suo risultato un lockfile anziché un resoconto. Nessun rendering che una richiesta di grafo o di build esegue per sé fa nulla di tutto ciò.

Una build a cui si chiede di risolvere prima riceve risposta proprio da quel rendering, ed è per questo che esegue il rendering della Release una sola volta. La risoluzione ha già eseguito il rendering di ciò che riguarda la build, rispetto ai pin appena scritti e sotto i controlli che una build esegue, quindi la build presenta quel rendering anziché eseguirne un secondo — e l’acquisizione resta di competenza della risoluzione anziché della build. Solo un rendering che si è concluso viene usato così: quando una risoluzione ha fissato le proprie dipendenze ma non è riuscita a finire di scoprire i riferimenti esterni, la build esegue il rendering per conto proprio rispetto ai pin effettivamente scritti, e un riferimento non fissato viene rifiutato e segnalato lì esattamente come in una build che non ha risolto nulla.

Il rifiuto viene segnalato anziché assorbito, perché nulla in un risultato dice quale riferimento vi mancasse. Con i provider inclusi in questo binario, il provider che ha richiesto il riferimento restituisce il rifiuto, quindi un rendering che ha raggiunto un riferimento rifiutato non si completa. Ogni riferimento rifiutato arriva perciò come voce a sé sul layer aggrega-build, con il nome del riferimento e del comando che lo fissa: aggrega pull --release <release>, oppure aggrega/resolveDependencies per lo stesso lavoro senza lasciare la sessione. Le voci sono consultive anziché un rifiuto — il grafo viene comunque restituito, con lo stesso status che ha l’avviso di drift visto sopra — e sono attribuite all’Aggregate in testa al file, perché un riferimento richiesto da un rendering non nomina alcuna chiave scritta da un autore. Viaggiano nella stessa pubblicazione degli avvisi propri del rendering, che sostituisce quel layer per intero, quindi un riferimento che poi fissi smette di essere segnalato senza che nulla debba cancellarlo. Un rendering completamente fissato non dice nulla di tutto ciò. Vedi Che cosa contiene una voce di diagnostica per la forma che assume ciascuna voce.

Su aggrega/irGraph questo dipende dal fatto che la fase di rendering venga eseguita. La richiesta di grafo salta il rendering a meno che --build-on-inspect, o la chiave serve.build_on_inspect che esso sovrascrive, non lo attivi; con l’opzione disattivata nulla richiede un riferimento esterno e non c’è nulla da rifiutare. Attivarla è ciò che porta in una sessione dell’editor sia gli avvisi propri del rendering sia questi.

In che cosa una sessione differisce dallo stesso congelamento alla riga di comando. aggrega build congela gli input esterni anche per un dry run, e un riferimento non fissato si comporta allo stesso modo su entrambe le superfici: viene segnalato come una rilevazione che nomina il riferimento, e il rendering poi si arresta, perché il provider che lo ha richiesto restituisce il rifiuto. Ciò che differisce è il nuovo download. Alla riga di comando un riferimento fissato la cui copia memorizzata è andata persa viene scaricato di nuovo tramite il suo digest registrato; il rendering che risponde a una richiesta di grafo o di build non riscarica nulla, perché quel rendering non raggiunge alcuna rete, quindi non può tornare a prendere un riferimento fissato che lo store non contiene più — e un tale riferimento non è tra i rifiuti descritti sopra, che nominano ciò che il lockfile non fissa. Chiedere a una sessione di fissare è ciò che lo recupera: le richieste nominate sopra raggiungono la rete e rimettono a posto i byte mancanti. Vedi aggrega pull per ciò che il pinning scarica e registra.

Che cosa ti dice comunque un’esecuzione rifiutata

Una richiesta che rifiuta risponde con un envelope di errore, e le rilevazioni che l’esecuzione aveva già fatto non viaggiano dentro quell’envelope — l’envelope non contiene alcun corpo del risultato. Ti raggiungono come ti raggiungono in un’esecuzione che si è conclusa: come una pubblicazione di diagnostica sul layer aggrega-build, descritta in Che cosa contiene una voce di diagnostica. Quindi un client che gestisce un rifiuto legge l’envelope per sapere che cosa cambiare e la propria superficie dei problemi per sapere che cosa ha trovato l’esecuzione, e nessuno dei due sostituisce l’altro. Un rifiuto sollevato durante il rendering è l’unico rifiuto che è anche una rilevazione su ciò che un autore ha scritto, quindi raggiunge entrambi, come descrive la sezione successiva.

Quella pubblicazione avviene che l’esecuzione sia arrivata o meno alla fine. Un’esecuzione che si ferma a metà ha comunque trovato tutto ciò che precede il punto in cui si è fermata, e un lettore che perdesse quelle rilevazioni dovrebbe eseguirla di nuovo per vederle — perciò gli avvisi vengono pubblicati a partire da ciò che l’esecuzione ha raggiunto, e il rifiuto viene restituito dopo. È lo stesso insieme con la stessa fedeltà, posizionato sulle stesse chiavi di authoring: un rifiuto non degrada una rilevazione a una frase. I riferimenti esterni rifiutati viaggiano in quella stessa pubblicazione, per lo stesso motivo e per la stessa via.

Ciò che la delimita è quanto è avanzata l’esecuzione, non ciò che il layer può contenere. Un rifiuto da uno dei controlli eseguiti prima che il compilatore parta — non è stato possibile risolvere la chiusura della Release, il Manifest mappa un tipo su una ricetta che non lo implementa, il lockfile non corrisponde più a ciò in cui la Release si risolve, una voce fissata nella cache non corrisponde più al digest registrato per essa e nessuna directory del catalogo contiene i byte fissati — non ha avvisi da pubblicare, perché non ne era ancora stato sollevato nessuno. Il layer allora non contiene nulla anziché qualcosa di obsoleto; e un’esecuzione che non è arrivata a nominare un documento non pubblica nulla, lasciando ciò che è già sulla tua superficie dei problemi esattamente com’era anziché cancellare voci di cui non ha appreso nulla.

Un rifiuto sollevato durante il rendering

Una Release che il compilatore rifiuta durante il rendering — un Workload che nomina uno slot che il suo Component non dichiara, un’asserzione che fallisce, un template che non può essere valutato, una realizzazione che non fornisce ciò che deve fornire — viene segnalata dove punta e con le parole del compilatore, su ogni richiesta che ne esegue il rendering: aggrega/build, aggrega/buildPreview e aggrega/irGraph con la fase di rendering attivata. La risposta è un envelope di errore con il codice -32603, il cui message è il rifiuto con ogni causa sotto di esso, nelle parole che la riga di comando stampa per la stessa build: il nodo di cui si sta eseguendo il rendering, poi ciò che in esso ha rifiutato, ogni causa dopo quella che spiega — preceduto, quando il rifiuto nomina una condizione registrata, dal codice breve di quella condizione, come lo è ogni rifiuto che ne nomina una. Il suo data nomina il documento a cui punta il rifiuto come file, e l’intervallo della chiave in quel documento come line, column, end_line e end_column, accanto a code e shortCode della condizione; un rifiuto che non nomina alcuna chiave, o una chiave che il documento non contiene, porta solo file, e uno che non punta ad alcun documento nomina l’Aggregate della Release.

Lo stesso rifiuto viene pubblicato sul layer aggrega-build, su quel documento, in quella chiave, come voce di severità error che porta il keyPath proprio del rifiuto e il message dell’envelope senza il codice breve davanti, e — quando il rifiuto nomina una condizione registrata — code, shortCode e codeDescription di quella condizione, con il codice breve che lì viaggia in un campo a sé. Viaggia nell’unica pubblicazione che porta gli avvisi sollevati dall’esecuzione prima che si fermasse, quindi sostituisce il layer come fanno loro: la successiva esecuzione della Release che esegue il rendering pubblica il layer senza di esso, e il documento su cui si trovava viene pubblicato vuoto, il che lo cancella dalla tua superficie dei problemi.

Il punto a cui un rifiuto punta è ciò che il rifiuto stesso nomina, e niente di più preciso. I controlli di un Workload giudicano il documento prodotto dal suo template, e un template può scrivere righe che nessun autore ha scritto — un ciclo, una condizione, un testo importato da un file o da una libreria — quindi una riga del Workload renderizzato non corrisponde a una riga della Recipe. Un rifiuto relativo a un Workload viene quindi collocato sulla chiave workload della Recipe, e i percorsi che nomina all’interno del documento renderizzato restano nel suo messaggio. Un’asserzione che fallisce viene collocata sulla propria chiave sotto assertions nella Recipe o nella FeatureRecipe che la dichiara; un’asserzione che un Component o una Feature dichiara viene sollevata prima che sia disponibile un documento da nominare, ed è collocata sulla chiave kind: dell’Aggregate. Un rifiuto da un passaggio che nomina un documento ma nessuna chiave viene collocato sulla chiave kind: di quel documento.

Un rifiuto che riunisce più rilevazioni viene pubblicato rilevazione per rilevazione. La composizione del grafo da cui lavora il rendering rifiuta con ogni violazione trovata in un unico rifiuto — una voce che nomina un target a cui nulla risponde, due connessioni di un componente con lo stesso alias — e la riga di comando stampa ciascuna come una diagnostica a sé, sotto la propria intestazione. Qui ciascuna è una voce a sé sul layer aggrega-build, sul documento e nella chiave che quella rilevazione nomina — la Release dove l’ha scritta la Release, l’Aggregate dove l’ha scritta l’Aggregate — con le proprie parole e i propri codici. Il message della risposta porta ogni rilevazione, e il suo data nomina dove punta la prima.

Un valore che un autore ha dichiarato sensibile viene nascosto qui esattamente come lo nasconde la riga di comando. Il testo del rifiuto è il testo sollevato dal compilatore, nulla su questa superficie lo riformula, e il compilatore nasconde un valore dichiarato nel punto in cui il rifiuto viene sollevato — con <redacted> al suo posto — quindi questa risposta, questa voce e il terminale lo riportano con le stesse parole; che cosa dice un rifiuto su un valore dichiarato spiega come, e quali rifiuti ne restano fuori.

Un rifiuto da un controllo eseguito prima del rendering non è questo. I controlli elencati sopra rispondono come descrive Che cosa ti dice comunque un’esecuzione rifiutata. Un’asserzione che un Component o una Feature dichiara, e un rifiuto sul grafo composto, stanno a metà tra i due: ciascuno viene sollevato prima del rendering, da ogni richiesta che risolve il grafo di una Release, quindi aggrega/irGraph lo restituisce e lo pubblica come sopra anche con la fase di rendering disattivata; aggrega/releaseClosure, aggrega/attachCandidates e aggrega/attachmentContainer interrogati su un nodo del grafo, e aggrega/connectionAtPosition, lo restituiscono con lo stesso envelope e non pubblicano nulla, perché non possiedono alcuna superficie dei problemi.

Codici di errore

Le risposte usano i codici di errore standard di JSON-RPC più un intervallo a livello applicativo nella fascia 1xxx. Un client dell’editor può diramarsi in base al codice senza analizzare il messaggio.

  • 1001 file-not-validated (file non validato) — il daemon non possiede, per il file così com’è ora, nulla da cui si possa rispondere alla richiesta: nessun parsing del file oppure, per aggrega/diagnostics, nessun parsing del file o nulla di conservato per il file che sia la risposta di una validazione per il testo che il daemon possiede ora. Invia aggrega/validate per quel file e chiedi di nuovo.
  • 1003 lockfile-absent (lockfile assente) — la Release nominata dalla richiesta non ha un lockfile, e l’operazione richiesta ne ha bisogno.
  • 1004 entity-not-resolvable (entità non risolvibile) — il nome non corrisponde ad alcuna entità in nessun livello del catalogo, né nella Release nominata dalla richiesta; oppure il riferimento di registry inviato come nome non può essere letto come un’entità, e il messaggio nomina la condizione che spiega perché; oppure il lockfile della Release è un link che porta fuori dal workspace, il che viene rifiutato prima che qualcosa lo legga, con data che nomina il lockfile e la Release e il messaggio che si apre con il codice breve della condizione, E0321 — vedi il confine del workspace.
  • 1005 shutting-down (arresto in corso) — il daemon si sta svuotando dopo una notifica di arresto e rifiuta le nuove richieste. Non riprovare sullo stesso sottoprocesso.
  • 1006 validation-in-flight (validazione in corso) — una validazione del file è in esecuzione e non si è conclusa entro il tempo che la richiesta in attesa le ha concesso. Chiedi di nuovo a breve e non inviare nulla.

1002 non è assegnato, ed è disponibile per la prossima condizione che abbia bisogno di un codice.

File-not-validated e validation-in-flight segnalano stati opposti, e anche l’azione che ciascuno richiede è opposta. File-not-validated significa che il daemon non possiede, per il file così com’è ora, nulla da cui si possa rispondere alla richiesta — nessun parsing del file oppure, per aggrega/diagnostics, nessun parsing del file o nulla di conservato per il file che sia la risposta di una validazione per il testo che il daemon possiede ora: invia aggrega/validate e chiedi di nuovo. Una validazione annullata a metà lascia il file in questa condizione, perché non memorizza nulla e ciò che una validazione precedente ha trovato su un testo diverso non è una risposta per il testo che il daemon possiede ora; una risposta precedente resta valida finché il testo è quello che ha controllato. I risultati che il daemon invia su un file che ha letto da disco per conto proprio — un lockfile non più allineato, una Release che non si carica — non sono una validazione del testo che hai tu, quindi neanche loro rispondono a questa richiesta. Anche due validazioni di testi diversi inviate a breve distanza l’una dall’altra possono lasciarti in questa condizione, quando quella il cui testo il daemon ha conservato termina per prima: la richiesta viene rifiutata benché quel testo sia stato controllato, e validare di nuovo le dà risposta. È formulato in termini del parsing anziché del file perché un buffer che nessun parser leggerà si trova esattamente in quella posizione — la validazione è stata eseguita e ha segnalato ciò che ha trovato, e non c’è ancora alcun parsing da cui rispondere. Validation-in-flight significa che una sua validazione è in esecuzione e non si è conclusa entro il tempo che la richiesta in attesa le ha concesso: chiedi di nuovo a breve e non inviare nulla, perché lo stato di cui hai bisogno è già in arrivo e una seconda validazione aggiungerebbe solo lavoro. Leggere le due come un’unica condizione porta un client a inviare una validazione proprio nel caso in cui inviarla è la mossa sbagliata. Le due fasce significano cose diverse per un client: un codice 1xxx nomina uno stato del workspace su cui l’utente può agire — validare il file, generare il lockfile — mentre un codice standard come invalid-params nomina una richiesta malformata, che corregge il client anziché l’utente. Un valore release presente ma malformato — assoluto, o che si risolve fuori dalla radice del workspace — rientra nella seconda fascia: non è il workspace a trovarsi in uno stato che l’utente deve riparare, è la richiesta. Omettere release non rientra in nessuna delle due fasce, perché non è affatto un errore; seleziona la più ristretta delle due risposte descritte in Validazione dal vivo.

Un errore può portare un oggetto data, e ogni chiave in esso nomina una cosa e solo quella. file è il documento sorgente a cui si riferisce l’errore — il documento in validazione, la Release il cui caricamento è fallito, il documento del workspace che dichiara un nome che nulla ha risolto, o il documento a cui punta un rifiuto sollevato durante il rendering — ed è ciò all’interno di cui gli eventuali line e column che lo accompagnano individuano una posizione. Questi due sono a loro volta facoltativi: un errore relativo a un intero documento porta solo file. lockfile è un lockfile. release è la Release a cui si riferisce l’errore, scritta come la richiesta l’ha nominata, così un client può comporre aggrega pull --release <release> senza doverla estrarre dal messaggio. unreachable dice che il registry nominato da una richiesta rifiutata non è stato raggiungibile: lo porta un aggiornamento dell’indice rifiutato che nomina un registry, letto dall’errore stesso, e un registry che ha risposto lo lascia assente. Ogni chiave è facoltativa e presente solo quando il daemon ha in mano quel valore; nessuna sostituisce un’altra, quindi ciò a cui punta una chiave non dipende mai dal codice accanto.

code e shortCode in data nominano la condizione segnalata da un rifiuto, su ogni rifiuto che ne segnala una registrata, qualunque sia il suo codice numerico: il codice descrittivo su cui un programma si dirama e il codice breve che una persona cita, gli stessi due identificatori, con gli stessi nomi, che una voce di diagnostica porta per la stessa condizione, ed elencati nella tabella di tutte le condizioni. Diramati in base a code. Il codice numerico nomina lo stato della richiesta e resta lo stesso per molte condizioni — una build rifiutata perché un link del catalogo porta fuori e una build rifiutata perché un nome non si risolve in nulla sono entrambe 1004 — e il messaggio è prosa che può essere riformulata, quindi nessuno dei due distingue una condizione dall’altra. Invalid-params è uno di questi codici condivisi: lo provoca anche una richiesta che nomina un workspace il cui file di configurazione porta fuori da esso, e lì read-leads-out-of-workspace dice che il difetto è nella struttura del workspace, che ripara una persona, anziché nella richiesta. Un rifiuto che non segnala alcuna condizione registrata non porta nessuna delle due chiavi, e le due sono presenti insieme oppure per niente. Il messaggio di un rifiuto che nomina una condizione si apre con il suo codice breve, E0321: …, una sola volta, che è la forma che una persona incontra leggendolo su ogni rifiuto di questo tipo; a un rifiuto il cui messaggio si apre già con un’intestazione tra parentesi quadre che porta il codice — il resoconto su una riga di un documento del catalogo che il caricamento ha rifiutato — non viene aggiunto di nuovo.

Il resoconto di come è stata eseguita la cascata delle Release del workspace viaggia nella risposta di aggrega/activeRelease, nel suo campo trace, anziché in un errore: un workspace che non punta ad alcuna Release è uno stato ordinario anziché una richiesta fallita. È prosa diagnostica scritta perché la legga una persona, non una struttura da analizzare. Mostrala così com’è — scrivila in un log o in un pannello che l’utente può aprire — e non confrontarla con dei pattern, non estrarne valori e non diramarti in base alle etichette che usa: la sua formulazione, la sua struttura e quelle etichette seguono la cascata stessa e cambiano ogni volta che cambia la cascata. Un client che passa il testo così com’è continua a funzionare attraverso un tale cambiamento; uno che ne ha imparato la forma si rompe.

Vedi anche

  • ../schema/other/serve-wire.md — le forme dei messaggi che questo protocollo scambia, generate dallo schema pubblicato: l’oggetto dei parametri di ogni metodo, ogni risultato e ogni payload di notifica, campo per campo.
  • ./aggrega-build.md — il comando build, la cui pipeline del compilatore, i cui controlli e la cui risoluzione delle dipendenze sono eseguiti anche da aggrega/build, così le due superfici scrivono un unico albero di output anziché due.
  • ./aggrega-version.md — il comando version che un’estensione dell’editor usa per verificare la compatibilità del daemon.
  • ./aggrega-pull.md — il lockfile che legge la superficie di drift del daemon.
  • ./aggrega-lint.md — le convenzioni di pubblicazione che il daemon segnala su richiesta, e a ogni validazione una volta attivato serve.lint_on_validate.

Sinossi

aggrega serve [flags]

Descrizione

Run the Aggrega compiler as a long-running service. The daemon
reads JSON-RPC 2.0 messages from stdin and writes responses to stdout
under the aggrega/ method namespace. State (parsed YAML, diagnostics,
resolved catalog) holds across requests so IDE clients can issue many
cheap operations without re-paying per-invocation startup cost.
The daemon resolves its workspace root through the same path every
aggrega command uses: --workspace-root when set (used as-is, validated
to exist as a directory), otherwise discovery walking upward from the
current working directory. A directory anchors the workspace when it
holds a .aggrega-config.yaml carrying a workspace: block, or — as a
fallback — any of .aggrega/, aggregate*.yaml, release*.yaml,
manifest*.yaml.
Configuration is the cascade composition of the .aggrega-config.yaml
files from the workspace root down to the working directory (nearer
overrides farther), beneath which the global config file — the one
--config names, else the one the AGGREGA_CONFIG environment variable
names, else the default location when a file is there — and the
built-in defaults apply.
The daemon honors the aggrega/shutdown JSON-RPC notification for a
cooperative cross-platform exit: the daemon completes the in-flight
handler if any, refuses new requests with code 1005, and exits
cleanly within a 2-second drain budget.
Asking the process itself to stop — an interrupt from the terminal, or
a termination request from a supervisor or container runtime — takes
the same path on the same terms: the first request drains the daemon
and it exits cleanly, and a second ends the process at once.

Flag

FlagPredefinitoDescrizione
--build-on-inspectfalseEsegue la fase di rendering degli artefatti durante l’ispezione di un grafo IR, così gli avvisi che aggrega build solleva durante il rendering compaiono anche come problemi nell’editor. Non aggiunge nessuno dei controlli su cui una build si arresta. Non viene scritto nulla su disco: nessun artefatto renderizzato, nessuna directory di output, nessun lockfile. Disattivato per impostazione predefinita, in linea con aggrega inspect, che a sua volta non solleva alcun avviso di questo tipo. Se impostato, sovrascrive la chiave di configurazione serve.build_on_inspect.