aggrega serve
aggrega serve executa o Aggrega como um daemon de compilador como serviço de longa duração, para integração com IDEs. Fala JSON-RPC 2.0 sobre stdin/stdout e mantém o estado do resolvedor do catálogo, da cache de análise e dos diagnósticos entre pedidos, pelo que as operações do editor recebem resposta em menos de um segundo, em vez de pagarem o custo completo de carregar o catálogo a cada tecla premida.
O daemon é normalmente iniciado como subprocesso por uma extensão do editor, e não executado manualmente. Uma extensão do VS Code é o cliente de referência; outros editores podem integrar-se falando o mesmo protocolo.
O protocolo
O protocolo de comunicação é JSON-RPC 2.0 com enquadramento Content-Length, sob o espaço de nomes de métodos aggrega/. Intencionalmente, não é o Language Server Protocol — o Aggrega tem operações de domínio (uma consulta ao grafo IR, um sinal de invalidação da cache) para as quais o LSP não tem análogo. Uma extensão do editor traduz entre os pedidos LSP do editor e estes métodos aggrega/*; os valores de posição, intervalo e localização com a forma do LSP são reutilizados onde encaixam.
Dois métodos mantêm os seus nomes $/ padrão do protocolo, em vez de serem renomeados para o espaço de nomes aggrega/, porque ambos são questões de transporte que não têm nenhum significado Aggrega e um cliente que já fala o protocolo trata-os sem nada acrescentado: $/cancelRequest, que para um pedido para o qual o cliente já não quer resposta, e $/progress, que é como o daemon reporta uma operação longa enquanto decorre. Ambos são descritos abaixo.
🔴 Todos os pedidos abaixo contêm workspaceRoot, o caminho absoluto do espaço de trabalho sobre o qual atuam, e isso não é repetido por método. Três não o contêm, porque o seu objeto não é um espaço de trabalho: aggrega/initialize, aggrega/getSchema e aggrega/scaffoldEntity — exceto que aggrega/scaffoldEntity, ao escrever ou listar um exemplo executável, nomeia um. Consulte Todos os pedidos nomeiam o espaço de trabalho a que dizem respeito para o que recebe um pedido que não nomeie nenhum, e Declarar o espaço de trabalho para o qual se pretende que os diagnósticos sejam enviados para onde vão os diagnósticos enviados.
As formas campo a campo são publicadas como um esquema, e a referência das formas de comunicação é onde as ler. Essa página indica o objeto de parâmetros de cada método, cada resultado e cada conteúdo de notificação — cada campo com o seu tipo, se é obrigatório e o que contém — juntamente com três propriedades que valem para toda a superfície e não por método: os dois campos que todos os pedidos admitem para além dos que o seu próprio método declara, que são workspaceRoot acima e o workDoneToken de Acompanhar uma operação longa; que um objeto de parâmetros com uma chave que o seu método não aceita é recusado, com o conjunto aceite nomeado na recusa; e onde uma coleção ausente chega à comunicação como null e não como uma coleção vazia. É gerada a partir desse esquema, pelo que muda quando o contrato muda.
Esta página contém o protocolo, aquela contém as formas, e devem ser lidas em conjunto. Aqui: o enquadramento, para que serve cada método, até onde chega, o que escreve, que recusas levanta e porquê, os códigos de erro e o que fazer perante cada um. Ali: o que colocar na comunicação, chave a chave. Assim, a lista abaixo nomeia cada método e diz o que significa pedi-lo, e a lista de campos do pedido que se está a compor está na referência ao lado.
Pedidos:
aggrega/initialize— aperto de mão. Negoceia a codificação de posições (o servidor prefere UTF-8, depois UTF-16, depois UTF-32, e por predefinição usa UTF-16), recebe o espaço de trabalho declarado para os diagnósticos enviados e reporta a raiz desse espaço de trabalho, a camada de configuração a partir da qual as suas definições foram resolvidas e o marcador que a resolveu. A resposta contém tambémversion, a versão do binário que responde: o mesmo valor queaggrega versionreporta para esse binário. Descreve o processo em execução, pelo que, depois de o ficheiro a partir do qual o daemon foi iniciado ter sido substituído — uma recompilação para o mesmo caminho, por exemplo —versioncontinua a nomear o daemon em execução, enquanto perguntar ao ficheiro nomeia o seu substituto; leia-o aqui quando a pergunta é com que versão se está a falar.workspaceRooté opcional e declara um espaço de trabalho em vez de atuar sobre um — consulte Declarar o espaço de trabalho para o qual se pretende que os diagnósticos sejam enviados. Enviecapabilities.window.workDoneProgress: truepara indicar que o cliente consegue tratar notificações de progresso; ocapabilities.workDoneProgressda resposta ecoa isso, e o campo está ausente para um cliente que não declarou nada. Consulte Acompanhar uma operação longa.aggrega/validate— validar o conteúdo de um ficheiro; devolve diagnósticos.releaseé um caminho relativo à raiz do espaço de trabalho que nomeia a Release em relação à qual validar — o mesmo valor queaggrega/irGraphaceita, e o mesmo valor queaggrega build --releaseaceita quando executado a partir da raiz. É opcional e seleciona até onde chega a resposta: nomeie uma Release e as verificações que precisam de uma são executadas em relação a ela — uma entidade do catálogo é verificada como uma única entidade nos termos dessa Release, e qualquer outro documento em relação ao fecho de dependências dessa Release; omita-a e a resposta abrange aquilo a que o documento pode ser vinculado por si só, e contémcheckedpara o indicar. Um valor presente mas malformado é recusado em qualquer caso — um caminho absoluto, ou um que resolva para fora da raiz do espaço de trabalho, é rejeitado em vez de resolvido. Consulte Validação em tempo real.aggrega/diagnostics— devolver as constatações mantidas para um ficheiro. Se estiver a decorrer uma validação desse mesmo ficheiro quando o pedido chega, a resposta espera por ela e reporta o que encontrou, pelo que a resposta nunca é um atestado de boa saúde para um ficheiro em que o daemon está a meio de encontrar problemas. Consulte Pedir diagnósticos enquanto decorre uma validação.aggrega/hover— conteúdo de hover para a entidade numa posição.releaseé opcional e responde nos termos dessa Release — consulte Responder nos termos de uma Release.aggrega/completion— candidatos de conclusão numa posição. Onde o cursor nomeia uma entidade pelo tipo — otypede um componente, otypede um anexo de Feature, um valorextends:, oimplements:de uma Recipe ou FeatureRecipe — os candidatos são os nomes desse tipo que os próprios documentos do espaço de trabalho declaram e, para um Component ou uma Feature, também os nomes que oscatalog_dirsconfigurados declaram, cada um oferecido uma vez e por ordem de nome. Um espaço de trabalho que obtém os seus Components e Features de um catálogo recebe-os, portanto, como oferta, e não apenas o que ele próprio escreveu. As Recipes e FeatureRecipes, oferecidas no valor de um mapeamento do Manifest, vêm dos próprios documentos do espaço de trabalho. Uma entidade que só a cache de artefactos ou um registo contêm não é oferecida: responder a uma conclusão nunca obtém nada.releaseé opcional e responde nos termos dessa Release — consulte Responder nos termos de uma Release.aggrega/resolve— resolver a entidade referenciada numa posição (ir para a definição).releaseé opcional e responde nos termos dessa Release — consulte Responder nos termos de uma Release.aggrega/findReferences/aggrega/findImplementations. Cada um aceita umareleaseopcional e responde nos termos dessa Release — consulte Responder nos termos de uma Release.aggrega/irGraph— o grafo IR compilado de uma Release, para introspeção pelo editor.releaseé um caminho relativo à raiz do espaço de trabalho, que nomeia uma Release dentro dele — o mesmo valor queaggrega build --releaseaceita quando executado a partir da raiz. Qualquer outra forma é recusada com o erro padrão de parâmetros inválidos, que nomeia o que enviar em vez disso: um caminho absoluto, um caminho que resolve para fora da raiz do espaço de trabalho — quer saia tal como está escrito, quer conduza para fora através de uma ligação, até ao ficheiro ou até um diretório pelo caminho — e um valor vazio são todos rejeitados em vez de resolvidos, pelo que um pedido nunca reporta sobre um ficheiro que o espaço de trabalho não contém. Uma Release que a configuração do espaço de trabalho nomeia, comobuild.authoring_releaseou como chave deworkspace.releases, é uma que o espaço de trabalho contém onde quer que o seu ficheiro se encontre, pelo que uma ligação dentro do espaço de trabalho que conduza a ela é aceite, tal comoaggrega/releaseCandidatesa lista. Um diretório de catálogo que a Release lê e que não pode ser percorrido — um que existe e não pode ser lido, por exemplo — é recusado comoaggrega inspecto recusa, antes de qualquer outra leitura: o erro é1004entity-not-resolvable, a sua mensagem é o relatório que a linha de comandos imprime para esse diretório, numa linha ([CATALOG_ERROR] <directory>: catalog load: …), e nenhum grafo é traçado sobre os diretórios restantes. Um diretório que a configuração do espaço de trabalho lista e que não é um diretório — nada existe lá, por exemplo — é recusado da mesma forma e no mesmo momento,1004entity-not-resolvable, sendo a sua mensagem a recusa que todos os comandos lhe dão, que nomeia a entrada, o ficheiro de configuração e a linha que a listam e a opção (De onde são lidas as entidades locais). Um diretório de catálogo que contenha uma ligação que conduza para fora do diretório dentro do qual as suas leituras têm de ficar — um documento ou um diretório ligado a partir de outro sítio, sob um diretório de catálogo dentro do espaço de trabalho ou sob um que a configuração nomeia fora dele — é recusado da mesma forma e no mesmo momento, com1004e a própria frase da condição, que nomeia a ligação e para onde conduz: nada é lido através de uma ligação destas, e um grafo traçado sem ela poderia resolver outra entidade com o mesmo nome no seu lugar. O mesmo acontece a uma ligação para fora entre os documentos junto da Release, onde a Release nomeia o seu Aggregate ou o seu Manifest pela identidade. Um ficheiro que a Release, o seu Manifest ou uma Release que ela estende nomeiam por um caminho —aggregate:,manifest:,extends:ou um$import:de parâmetros — e que conduz para fora do espaço de trabalho, tal como está escrito ou através de uma ligação, é recusado com a própria frase da condição (fatal-halts.md §«A reference to another file leads out of the directory it must stay inside (Uma referência a outro ficheiro sai do diretório dentro do qual deve permanecer)»), com os dados do erro a situá-lo na chave da Release que conduziu ao ficheiro, e nada é lido desse ficheiro; uma Release que a configuração nomeia fora do espaço de trabalho é vinculada da mesma forma ao diretório que a contém, pelo que um caminho que ela, ou uma Release a que a sua cadeia conduz, escreve e que sai desse diretório é também recusado. Note queaggrega/releaseCandidatesresponde com caminhos absolutos, pelo que um cliente que alimente uma superfície com a outra converte entre ambos. Que este parâmetro recuse uma grafia que os parâmetros por documentofileeuriaceitam é deliberado, e Que grafias aceita um parâmetro enviado diz o que o decide. O grafo oculta todos os valores que um autor declarou sensíveis, exatamente como--ir-graphos oculta na linha de comandos: cada um é substituído pelo marcador queaggrega-inspect«Saída legível por máquina» descreve, e tudo o resto é transportado tal como o compilador o registou.unredacted: truepede esses valores em claro — a grafia do protocolo para o--unredactedda linha de comandos, e a única forma de os pedir; ausente oufalse, a resposta oculta-os. Tudo aquilo a que a resposta chegar contém então os valores em claro, pelo que um cliente só os pede onde a pessoa que o utiliza o fez.aggrega/build— compilar uma Release e escrever os seus artefactos no diretório de saída do espaço de trabalho, o mesmo diretório em queaggrega buildescreve quando é executado a partir da raiz do espaço de trabalho.releasetem o mesmo contrato que acima. Renderiza com todas as verificações ativas, pelo que uma divergência perante a qual um build de linha de comandos pararia também para aqui. Um diretório de catálogo que a Release lê e que não pode ser percorrido — um que existe e não pode ser lido, por exemplo — é recusado tal comoaggrega buildo recusa, antes de qualquer escrita: nenhum artefacto, e nenhum lockfile quandoautoPullestá definido. O mesmo acontece com um diretório que a configuração do espaço de trabalho lista e que não é um diretório, nos termos em queaggrega buildo recusa (De onde são lidas as entidades locais). A recusa é a queaggrega/irGraphdá para o mesmo diretório,1004entity-not-resolvable com o relatório da linha de comandos numa só linha, e uma ligação que conduz para fora das leituras de um diretório de catálogo, ou dos documentos ao lado da Release, é recusada tal comoaggrega/irGrapha recusa, sem que nada seja escrito. A resposta indica ooutputDirectoryem que escreveu e osfilesque escreveu, cada um relativo a esse diretório e ordenados, juntamente com quaisquernoticesque a execução tenha gerado; as constatações que têm uma posição no documento seguem antes poraggrega/publishDiagnostics. A uma Release que recusa durante a renderização responde-se com essa recusa nas palavras do compilador, com todas as causas, e a recusa é publicada onde aponta — ver Uma recusa gerada durante a renderização. QuandoautoPullestava definido, a resposta contém tambémdependencyResolution, o mesmo relatório com queaggrega/resolveDependenciesresponde, pelo que um cliente que preencheu as dependências como parte do build lê o que foi fixado sem voltar a perguntar — e de onde a resolução deste build tirou cada referência, um facto sobre essa execução que o lockfile não regista. Cada aviso tem aclassda superfície que o gerou —deprecation,catalog,catalog-lint,extends,release-composition, oudependency-resolutionpara uma linha gerada pela resolução de dependências descrita abaixo — e umaclassvazia quando o daemon não tem nome para essa superfície, que um cliente apresenta como otextsimples em vez de adivinhar a correspondência mais próxima. Os ficheiros que a escrita encontra no diretório de saída, ou num diretório abaixo dele em que escreveu um ficheiro ou pelo qual passou, e que este build não escreveu ficam onde estão e são nomeados num único aviso a seguir aos da própria execução, sob umaclassvazia, na frase com queaggrega buildimprime o seu alerta — ver Ficheiros que o build não escreveu;filesnunca os nomeia.outputParentindica para onde vão os artefactos dentro do espaço de trabalho, e o seu nome é tudo o que significa: é o diretório dentro do qual o diretório de saída é criado, pelo que enviardocsescreve os artefactos emdocs/diste não no própriodocs— exatamente o que produz um build executado emdocsnum terminal. Se for omitido, o build escreve onde escreve uma execução na raiz do espaço de trabalho. Lê-se de forma diferente dooutputDirque os outros pedidos de escrita aqui aceitam, e propositadamente: esses nomeiam o diretório no qual se escreve, este nomeia o diretório pai desse, e os dois têm nomes diferentes porque são coisas diferentes. Continua a ser um destino dentro do espaço de trabalho, pelo que um valor absoluto, um que sobe para fora da raiz e um que sai dela através de uma ligação — um diretório ligado fora da raiz, ou um diretório ainda não criado abaixo de um desses — são recusados em vez de resolvidos. O diretório de saída criado dentro dele, e cada ficheiro que o build lá escreve, ficam também restritos ao espaço de trabalho: quando um deles sai do espaço de trabalho através de uma ligação, o build é recusado com1004e a frase própria da condição, que nomeia a ligação e para onde conduz, e nada é limpo nem escrito.autoPullresolve as dependências da Release antes da renderização, a mesma resolução queaggrega/resolveDependenciesefetua, e está desativado a menos que um pedido o solicite, em linha com a predefinição da própria linha de comandos; sem ele, uma Release que não tem lockfile é recusada com o erro lockfile-absent, que nomeia o que executar. ComautoPulldefinido, este pedido acede a registos e escreve o lockfile — ver Aceder a um registo, e escrever. Um pedido que resolve primeiro continua a renderizar a Release uma única vez: descobrir que referências remotas uma Release consome é já em si uma renderização, pelo que a resolução já renderizou aquilo de que trata o build, e responde-se ao build a partir dessa renderização em vez de a repetir.policyInputnomeia um diretório dentro do espaço de trabalho, relativo à sua raiz, no qual o build escreve também a carga útil que cada papel de governação entrega a um plugin aí anexado — os ficheiros queaggrega build --policy-inputescreve, com os mesmos nomes — quer o build termine, quer pare; osnoticesda resposta indicam então quantos foram escritos e nomeiam cada papel para o qual não foi escrito nenhum ficheiro, sob umaclassvazia. Num pedido que falha, os ficheiros escritos estão no disco e esse relato não consta da resposta: o envelope de erro contém apenas a recusa. É um destino, pelo que um valor absoluto ou um que sobe para fora do espaço de trabalho é recusado antes de qualquer execução.aggrega/buildPreview— reportar o que um build da Release escreveria, sem escrever nada.releasetem o mesmo contrato que acima. Executa o mesmo cálculo queaggrega/buildexecuta, com as mesmas verificações, pelo que uma Release ou seria recusada por ambos ou é reportada por ambos — o que faz da escolha entre eles uma escolha sobre a saída e não sobre o rigor. Um diretório de catálogo que a Release lê e que não pode ser percorrido, ou que contém uma ligação que conduz para fora do diretório dentro do qual as suas leituras têm de ficar, é recusado da mesma forma, antes de qualquer renderização, e o mesmo acontece com um diretório que a configuração do espaço de trabalho lista e que não é um diretório, como emaggrega/build. A resposta contémfiles, os nomes relativos à saída que um build emitiria, ordenados, juntamente com quaisquernotices; não háoutputDirectory, porque nada foi escrito em lado nenhum que se possa nomear. Uma Release que recusa durante a renderização é respondida e publicada exatamente comoaggrega/builda responde e publica. RecusaautoPullcom um erro de parâmetros inválidos que nomeia o que enviar em vez disso: preencher dependências escreve o lockfile, e este pedido não escreve nenhum lockfile. Não alcança nenhum registo.policyInputé a única escrita que faz, e só quando é enviado: escreve as cargas úteis de governação nesse diretório exatamente comoaggrega/buildfaz — os ficheiros queaggrega build --dry-run --policy-inputescreve — deixando intactos o diretório de saída e o lockfile, com o mesmo relato nosnoticese o mesmo limite: num pedido que falha, os ficheiros escritos estão no disco e o relato não consta da resposta.aggrega/resolveDependencies— resolver as dependências de catálogo e de origem da Release para a cache, fixar as entradas externas que a sua renderização consome no armazenamento endereçado por conteúdo e escrever o seu lockfile.releaseé um caminho relativo à raiz do espaço de trabalho, o mesmo valor queaggrega/irGraphaceita e recusado nas mesmas formas.upgradedescarta as fixações registadas e volta a resolver, fazendo flutuar cada dependência para a versão mais alta disponível;targetsrestringe isso às referências de entidades que nomeia, mantendo todas as outras fixações.verifyverifica a resolução registada em relação à que este pedido executaria sem ele, respeitando as fixações registadas da mesma forma, e não escreve nenhum lockfile, registo de confiança de plugins ouentity.lock— a cache é lida e preenchida como seria sem ele — respondendoverified: truee otoolchainque o lockfile regista.verifyé recusado como parâmetros inválidos juntamente comupgrade, comtargetse compinSources, seja qual for o valor que este contenha, antes de qualquer resolução ou de qualquer progresso ser reportado: uma atualização elimina as fixações que uma verificação existe para respeitar, os alvos nomeados só são resolvidos de novo por uma atualização, epinSourcesdecide se uma resolução regista as fixações que faltam numentity.lockou as recusa, nenhuma das quais uma comparação que não escreve nenhumentity.lockfaz. A linha de comandos e a ferramenta do assistente recusam os mesmos pares. A resposta nomeia olockfileque escreveu ou com que comparou e cada referência que fixou, ementities,librarieseplugins, cada entrada com aversionpara que resolveu e a suasource— de onde esta execução retirou a referência, na palavra queaggrega pull --detailimprime para a mesma resolução:fetched-fresh,cache-reuse,local,in-binaryouexternal— juntamente comsourceArtifacts,trustedPlugins,externalInputs— quantas entradas externas o lockfile fixa quando a execução termina, contando tanto as transportadas como as que esta execução descobriu — e quaisquernoticesque a resolução tenha levantado. 🔴 Uma resposta bem-sucedida não significa por si só que a fixação de entradas externas está completa. Onde a execução fixou todas as dependências mas não conseguiu terminar de determinar que entradas externas a Release consome, responde comincompleteExternalInputs, indicando o que parou a descoberta, e continua a responder como êxito — as fixações de dependências estão completas e no disco, pelo que reportar o pedido inteiro como falhado mandaria refazer trabalho que já está correto. Leia esse campo antes de tratar um lockfile como totalmente fixado: está ausente quando nada ficou por descobrir, pelo que a sua presença é o sinal. Não há nenhum parâmetro de diretório de catálogo: a pilha de pesquisa é a que o espaço de trabalho configura. Este é o único pedido de fixação da sessão para uma Release, e é onde as entradas externas também são fixadas — os URLs que uma renderização consome decorrem do que renderiza, pelo que este pedido renderiza a Release para o descobrir, e um pedido de build é depois servido a partir do que registou. Uma Recipe ou FeatureRecipe que a Release constrói cujoentity.locknão regista nenhuma fixação para uma entrada que a entidade lê recusa o pedido, nomeandoaggrega pine cada entrada não registada;pinSources: trueexecuta esse passo de fixação sobre essas entidades em vez disso, escrevendo oentity.lockjunto de cada uma — o mesmo passo queaggrega/pinexecuta, escrevendo os mesmos bytes. Ausente,pinSourcessegue opin_sources_at_pulldo espaço de trabalho; enviado, substitui essa definição nos dois sentidos, pelo quefalserecusa mesmo num espaço de trabalho configurado para fixar. Este pedido alcança registos e escreve — consulte Alcançar um registo, e escrever.aggrega/pin— registar, noentity.lockjunto de uma Recipe ou FeatureRecipe, a fixação de conteúdo de cada entrada que a entidade lê de fora do seu próprio documento: uma origem remota cujas coordenadas estão escritas por extenso, um ficheiro que uma entrada artifacts importa e cada ficheiro com que uma origem local contribui para o que uma publicação da entidade transporta. É o mesmo passo queaggrega pinexecuta num terminal, e escreve os mesmos bytes.entityé obrigatório e é um caminho relativo à raiz do espaço de trabalho que nomeia o documento da entidade, recusado nas mesmas três formas querelease. Nenhuma Release é nomeada: uma origem remota cujas coordenadas não têm modelo nomeia um único artefacto para todas as Releases que utilizam a entidade, pelo que nada do que uma Release fornece é necessário para a fixar, enquanto uma origem remota cujas coordenadas vêm de um modelo é fixada por Release poraggrega/resolveDependencies; uma origem local escrita como modelo contribui com todos os ficheiros do diretório da entidade, e cada um deles é fixado aqui.dryRunresolve as entradas e responde com o lock que o passo escreveria comocontent, sem escrever nada junto da entidade; a cache de conteúdo continua a ser preenchida. A resposta contémentity,kind,nameepinnable— false para um tipo que não lê nada que um lock registe, caso em que nada junto da entidade foi tocado e todos os outros campos estão ausentes — e, caso contrário, olockque escreveu,changed(false quando o lock já registava todas as fixações e ficou idêntico byte a byte),removedonde a entidade já não lê nada que um lock registe e o seu lock foi apagado, epins, uma entrada por classe de fixação com a contagem que o lock contém. O próprio ficheiro da entidade nunca é escrito. Isto escreve junto da entidade, dentro do espaço de trabalho, e alcança os anfitriões que as origens da entidade nomeiam — consulte Alcançar um registo, e escrever.aggrega/cacheStatus— o que as caches em disco contêm: uma entrada por elemento em cache com o seu tamanho e, onde o tenha, o seu digest de conteúdo, agrupados por classe. Aceita o espaço de trabalho e mais nada. Cada classe contém umreach—workspacepara a cache de artefactos sob o próprio diretório de cache deste espaço de trabalho,machinepara os armazenamentos de módulos compilados, de descrições de plugins e de pacotes de documentação que todos os projetos da máquina partilham — escopenomeia diretamente as classes de toda a máquina. Não escreve nada. Consulte Alcançar um registo, e escrever para saber porque é que o alcance está numa resposta que não altera nada.aggrega/cachePrune,aggrega/cacheEvict,aggrega/cacheClear— recuperar conteúdo em cache. Uma poda remove o que nenhum lockfile do espaço de trabalho referencia; uma expulsão reduz o armazenamento de módulos compilados amaxSize, uma quantidade de bytes escrita como a linha de comandos a escreve (5GiB,512MiB, ou uma contagem de bytes); uma limpeza apaga todas as caches que esta sessão endereça. Cada resposta nomeia o que removeu, com cada remoção a conter oreachda classe de onde veio, e cada uma contémscope. Cada resposta nomeia também o que deixou no lugar porque outro processo o tinha aberto — o Windows recusa remover um ficheiro aberto, e a operação continua com o resto em vez de falhar: uma poda ou uma expulsão lista essas entradas emheldOpen, e uma limpeza conta, para cada cache que esvaziou, os ficheiros que deixou emheldOpenFilese o seu tamanho emheldOpenBytes. Nos outros sistemas a lista está vazia e as contagens são zero, e uma execução posterior pode recuperar o que ficou. Estes vão além do espaço de trabalho — consulte Alcançar um registo, e escrever.aggrega/registryList— os registos que este espaço de trabalho está configurado para alcançar: o anfitrião de cada entrada, o alias opcional, se é o predefinido, a sua postura de confiança como campos discretos e se está presente uma credencial para esse anfitrião. Aceita o espaço de trabalho e mais nada. Não contacta nenhum registo. O estado da credencial reporta apenas a presença — nunca a credencial, nunca a sua forma e nunca se o registo a aceitaria, o que exigiria uma ida e volta pela rede que uma listagem não faz — e é lido do armazenamento de credenciais de toda a máquina, o quecredentialStateIsMachineWidediz explicitamente.aggrega/search— pesquisar o índice local dos registos configurados. Todos os campos restringem e todos são opcionais, pelo que um objeto de parâmetros vazio pede tudo o que o índice contém. Não contacta nenhuma rede: o índice é o instantâneo offline escrito sob o próprio diretório de cache deste espaço de trabalho. A versão reportada é a que uma resolução tomaria — uma versão cuja retirada tem uma assinatura em que este espaço de trabalho confia é excluída e nomeada emretracted— e a resposta contém a sua própria proveniência:indexesdá a idade do instantâneo de cada registo pesquisado,stalemarca um que vale a pena atualizar, emissingIndexHostsnomeia os registos configurados sem índice local, cujo conteúdo está, portanto, ausente da resposta.aggrega/registryAdd— registar um registo e a sua política de confiança de assinaturas.hosté obrigatório; tudo o resto molda a política ou o destino da escrita.keyPathetrustedRootnomeiam ficheiros: um valor absoluto — um ficheiro escolhido numa caixa de diálogo, por exemplo — é lido onde indica; um relativo nomeia um ficheiro dentro do espaço de trabalho, resolvido em relação à raiz do espaço de trabalho e não ao diretório onde o daemon é executado, e um que saia da raiz ou conduza para fora dela através de uma ligação é recusado com o erro de parâmetros inválidos antes de qualquer leitura ou escrita. UmtrustedRootrelativo é registado como o ficheiro que nomeia no espaço de trabalho, pelo que a entrada nomeia esse ficheiro seja qual for o diretório em que uma verificação posterior é executada.fetchTrusté por predefinição true quando a chave está ausente, correspondendo à linha de comandos, e adota a política anunciada pelo próprio registo no primeiro contacto;trustna resposta diz o que aconteceu — a política foi fixada, o registo não anunciou nenhuma (e, comunreachableao lado, não pôde de todo ser alcançado), a base incorporada do hub oficial foi fixada em seu lugar, ou não foi tentada nenhuma obtenção. O registo é o queaggrega registry addexecuta: a mesma obtenção sob a mesma postura de rede, escrevendo a mesma entrada byte a byte. Num espaço de trabalho offline, a obtenção é recusada antes de qualquer ligação, pelo que o registo nunca é consultado, e um registo que não seja o hub oficial é recusado, a menos que o pedido forneçaidentitiesoukeyPath, que registam exatamente o que foi enviado e não fazem nenhuma obtenção: a mensagem do erro é a frase que a linha de comandos imprime, precedida do código curto da condição,E0310— tal como a mensagem de todas as recusas deste pedido que nomeiam uma condição começa pelo seu código curto — e nada é escrito. O hub oficial continua a ser escrito com a sua base incorporada, respondido comtrust.baselineverdadeiro etrust.reasona dizer que não foi pedida ao hub a sua política de confiança porque o espaço de trabalho está offline — a razão com que o aviso da linha de comandos começa — e semnotAdvertised, porque o hub nunca foi consultado. Isto escreve a configuração global por predefinição — consulte Alcançar um registo, e escrever.aggrega/registryRemove— eliminar a entrada de um registo, indicado pelo anfitrião ou pelo alias amigável. Um token que não corresponda a nada é recusado em vez de ser respondido como êxito sobre uma configuração inalterada. Isto escreve a configuração global por predefinição — consulte Alcançar um registo, e escrever.aggrega/logout— remover a credencial guardada de um registo, a mesma remoção queaggrega logoutexecuta num terminal.registryé obrigatório e nomeia o anfitrião do registo tal como foi usado na autenticação; não há aqui nenhum alias amigável a resolver, porque o armazenamento de credenciais está indexado pelo endereço com que um cliente se autentica e não por algo que uma configuração nomeie, pelo que um anfitrião que nenhum espaço de trabalho configura pode ainda ter uma credencial que se pode remover. Um anfitrião para o qual o armazenamento não tem credencial é removido com êxito e nada é reescrito — um chamador que pediu que um anfitrião não tivesse credencial obteve o que pediu, pelo que isso é uma resposta e não um erro, e é também o que o comando de terminal faz. A resposta contémregistryescope. Não contém nenhuma parte da credencial sob nenhuma forma, e não reporta nada sobre se existia uma: estabelecê-lo exigiria uma segunda leitura do armazenamento que ninguém pediu, pelo que deve perguntar aaggrega/registryListquando a questão é a presença. Não contacta nenhum registo — remover uma credencial guardada é um ato local, e não se pergunta se esse registo teria aceitado a credencial. Isto altera o armazenamento de credenciais que todos os projetos da máquina partilham — consulte Alcançar um registo, e escrever.aggrega/registryUpdate— atualizar o índice local pesquisável queaggrega/searchlê. Umregistryausente atualiza todos os configurados; nomear um atualiza apenas esse registo.upgradevolta a ler integralmente todos os repositórios, sem comparar nada com o índice já escrito; uma atualização sem ele já volta a ler tudo o que mudou. A resposta contém a contagem de registos de cada anfitrião, os repositórios que não conseguiu ler — cada um com umreasonque começa pelo tipo da última falha da leitura, quando existe uma —,readsRetried, quantas das suas leituras o registo recusou ou interrompeu pelo caminho e foram pedidas de novo, cada uma contada uma vez e zero incluído, os marcadores de descontinuação que encontrou, oerrorde um anfitrião que falhou — comunreachableao lado onde esse registo não pôde ser alcançado — eindexRoot, o diretório sob a própria cache deste espaço de trabalho onde os índices foram escritos. Isto alcança todos os registos que atualiza — consulte Alcançar um registo, e escrever.aggrega/publishEntity— empacotar uma entidade do catálogo e publicá-la num registo.entityé um caminho relativo à raiz do espaço de trabalho que nomeia o documento a publicar, recusado nas mesmas três formas querelease— ausente, absoluto ou a resolver para fora da raiz. Uma entidade Plugin precisa também deplugin, o mesmo tipo de caminho, que nomeia o executável publicado dentro do próprio manifesto da entidade.registryé o destino e, por predefinição, é o configurado no espaço de trabalho.dryRuncalcula o pacote e o digest que uma publicação dele depositaria, e não contacta nenhum registo. Omitirsignsegue a própria política do registo de destino, que é o que a linha de comandos faz quando a sua opção está ausente, enquanto enviá-lo é escolha do chamador — e nenhum dos dois relaxa a recusa, porque uma política de registo ou de espaço de trabalho que exige uma assinatura recusa uma publicação não assinada, diga o campo o que disser.pinSources: trueexecuta o passo de fixação do autor da entidade sobre a entidade antes de a empacotar, para que oentity.lockque o passo escreve ao seu lado faça parte do que é publicado — o mesmo passo queaggrega/pinexecuta. É executado antes de qualquer recusa que avalie o conteúdo da entidade — uma política de assinatura, a proteção de imutabilidade — pelo que uma publicação recusada aí deixa na mesma o lock escrito; uma recusa sobre o próprio pedido, como um espaço de trabalho offline ou nenhum destino, vem primeiro e não fixa nada, e o mesmo acontece com a recusa de uma entidade que partilha o seu diretório com outra entidade, em que o passo não pode escrever um lock. Ausente, segue opin_sources_at_pushdo espaço de trabalho; enviado, substitui essa definição nos dois sentidos. ComdryRun, o passo reporta o lock que escreveria e não escreve nada. Uma publicação que não executa o passo recusa uma Recipe ou FeatureRecipe cujoentity.locknão regista nenhuma fixação para uma entrada que lê, ou uma a que a entrada já não corresponde, antes de qualquer empacotamento — também comdryRun— nomeandoaggrega pin,pinSourcesepin_sources_at_push; é a recusa queaggrega/resolveDependencieslevanta sobre o mesmo lock. A resposta contémreference,tag,kind,mediaType, o parsize, odigestpublicado — comdryRun, o digest que essa publicação depositaria, o queaggrega push --dry-runimprime —signed,alreadyPublished,dryRunereach;pin— a mesma resposta queaggrega/pindá — onde o passo foi executado; ewholeDirectorySourceonde a origem local da entidade está escrita como modelo, nomeando essa origem tal como escrita. Uma origem destas só escolhe o seu diretório quando uma Release preenche o modelo, pelo que a publicação transporta todos os ficheiros do diretório da entidade e não apenas os ficheiros que a entidade nomeia, e este campo é a forma de um chamador saber que o fez — também numa execução de teste. Contém aindawindowsUnusableEntriesonde o arquivo que a publicação transporta contém entradas que o Windows não consegue conter tal como estão escritas — um caminho com uma parte com o nome de um dispositivo, comoCON,AUXouNUL, em maiúsculas ou minúsculas e seja qual for a extensão que se siga, ou uma parte que termina num ponto final ou num espaço — nomeando cada uma, primeiro o próprio nome de ficheiro do documento da entidade e depois os ficheiros que transporta; está ausente onde não há nenhuma, o que inclui uma entidade publicada apenas como o seu documento.aggregaem execução no Windows recusa-se a desempacotar uma entrada destas, pelo que um espaço de trabalho Windows não pode utilizar a versão. Estas são as entradas sobre as quaisaggrega pushavisa, e um pedido que pediu relatórios lê as mesmas linhas de aviso entre o progresso da publicação; nenhuma delas recusa nada, pelo que a publicação avança ou é recusada exatamente como seria sem elas, também comdryRun. Isto escreve num registo e vai além desta máquina, e com o passo de fixação escreve também junto da entidade — consulte Alcançar um registo, e escrever.aggrega/publishArtifact— publicar um artefacto de dados autónomo, como um pacote de documentação.fileé um caminho relativo à raiz do espaço de trabalho, com o mesmo contrato, e os seus bytes são publicados literalmente: nenhum invólucro de entidade é analisado e nenhum tipo é usado para despachar.nameetagnomeiam aquilo sob que é publicado, e ambos são obrigatórios.mediaTypeé por predefinição o tipo do pacote de documentação. A resposta contémreference,tag,mediaType, o parsize, odigestpublicado,alreadyPublished,dryRunereach. Não assina nada — um artefacto publicado é assinado depois, por referência, comaggrega/signArtifacts, que só precisa da referência que esta resposta reporta. Isto escreve num registo e vai além desta máquina — consulte Alcançar um registo, e escrever.aggrega/signArtifacts— assinar artefactos já publicados e anexar cada assinatura.referencescontém um ou mais endereços de registo e não caminhos, pelo que não seguem o contrato relativo ao espaço de trabalho; uma lista vazia, ou uma entrada vazia nela, é recusada. Uma única identidade serve todo o lote e é resolvida antes de qualquer referência ser assinada, pelo que um lote sem nenhuma credencial disponível recusa logo no início e não a meio. O mesmo acontece a um lote cujas referências precisariam de credenciais diferentes: um pedido não nomeia nenhuma chave, pelo que se trata da configuração do espaço de trabalho a nomear uma chave detida para o registo de uma referência e nenhuma, ou outra chave, para o de uma segunda — nada é assinado, e a recusa nomeia os registos de cada lado, como descreve References signed together need different signing credentials (Referências assinadas em conjunto precisam de credenciais de assinatura diferentes). Assinar uma referência que nada publicou é recusado em vez de anexado a nada, e uma referência que já tenha uma assinatura que a política de confiança do seu registo verifica é deixada como está e contada como assinada, como descreveaggrega sign.jobs, que é opcional, indica quantas referências são assinadas ao mesmo tempo: se estiver ausente, são assinadas uma após a outra, e um valor inferior a 1 é recusado com o erro de parâmetros inválidos antes de qualquer referência ser lida. Cada referência continua a ser assinada exatamente como seria sozinha, como descreveaggrega sign, e tanto o progresso que o pedido reporta como a resposta mantêm a ordem em que as referências foram dadas. A resposta contémsigned, cada entrada a nomear umareferencee odigestpublicado com que a sua assinatura se compromete, juntamente comreach; um lote em que alguma referência falhou é respondido como falha, nomeando cada uma, e não como um resultado com uma lista curta. Isto escreve num registo e vai além desta máquina — consulte Alcançar um registo, e escrever.aggrega/deprecateArtifact— anexar um marcador de descontinuação assinado a um artefacto já publicado. Envie uma únicareferencecom a suaseverityereason, oufroma nomear um ficheiro de lote relativo à raiz do espaço de trabalho — enviar ambos é recusado. Os campos de conteúdo são obrigatórios em vez de pedidos interativamente: ninguém está a observar este fluxo, pelo que um pedido a que falte um é recusado, nomeando o que enviar. Pertencem apenas àreferenceúnica: um ficheiro de lote contém o conteúdo de cada marcador nas suas próprias entradas, pelo que umaseverity, umreason, umreplacementou umamessageenviados ao lado defromsão recusados como parâmetro inválido, nomeando cada um dos enviados, em vez de ignorados. Aplicam-se aqui as mesmas entradas keyless que os dois pedidos de assinatura aceitam, porque o marcador é assinado pelo seu próprio digest, e as entradas de um ficheiro de lote são vinculadas a uma única credencial exatamente como as referências de um lote de assinatura. A resposta contémmarked, cada entrada a nomear areferenceretirada, a suaseverity, o carimboissuedOne odigestdo próprio manifesto do marcador — o marcador é anexado como um referrer sem tag do artefacto que retira, pelo que nada mais o endereça — juntamente comreach. Isto escreve num registo e vai além desta máquina — consulte Alcançar um registo, e escrever.aggrega/catalogIndex— o índice de entidades: okind, oname, aapiVersion, adescription, aslabels, o ficheiro de origem e aoriginde todas as entidades do espaço de trabalho que o pedido nomeou. Aceita o espaço de trabalho e, opcionalmente,release: o conjunto é uma propriedade dessa raiz de espaço de trabalho e dos diretórios de catálogo que configura ou, comrelease, dos diretórios que a configuração atribui a essa Release — consulte Responder nos termos de uma Release. Abrange os dois sítios de onde uma entidade vem — os documentos Aggrega sob a raiz do espaço de trabalho e as Features que os diretórios de catálogo configurados contêm — porque esta é a superfície com que um cliente faz a junção quando precisa dos campos descritivos de uma entidade, e um índice que só conhecesse um dos dois deixaria parte de cada lista de candidatos por resolver. Um documento do espaço de trabalho conta como entidade quando declara tanto umkind:como ummetadata.namee não declara nenhumaapiVersionpertencente ao grupo de outro projeto, pelo que o YAML que por acaso esteja na árvore — o ficheiro de valores de um chart, uma configuração de CI, um manifesto Kubernetes renderizado — é ignorado em vez de listado. Um documento que não declare nenhumaapiVersioné reportado: é um documento Aggrega com um campo em falta, e vê-lo listado é a forma de descobrir que está lá para corrigir. Consulte Como uma entidade é endereçada para o que significamorigine umfilevazio. Nenhum documento por trás de uma ligação que conduza para fora da raiz do espaço de trabalho é lido: um diretório fora da raiz não é pesquisado, e um ficheiro fora dela não é lido, seja o que for que declare, pelo que uma entidade que o editor mostre sob uma ligação dessas não é listada como pertencente ao espaço de trabalho — nem oferecida poraggrega/attachCandidatesouaggrega/connectionCandidates, que leem os mesmos documentos, mesmo enquanto o editor tem esse documento aberto. Isso vale seja o que for que o documento declare. A única exceção é uma Release que a configuração do espaço de trabalho nomeia — comobuild.authoring_release, ou como chave deworkspace.releases, avaliada pelo ficheiro a que a ligação conduz, pelo que nomear a ligação ou esse ficheiro conta da mesma forma — que é lida, a partir do ficheiro a que a ligação conduz, e listada no próprio lugar da ligação, tal comoaggrega/releaseCandidatesa lista, e não é nomeada; um ficheiro que uma dessas definições nomeie e que declare outra coisa que não uma Release não é listado, e a sua ligação é nomeada. Os diretórios de catálogo configurados são a forma de um espaço de trabalho ler outras entidades guardadas noutro sítio, pelo que uma ligação para um diretório que a configuração lista sobcatalog_dirs— para o espaço de trabalho ou para uma Release — não é pesquisada como os próprios documentos do espaço de trabalho, nem nomeada: a configuração alcançou-a, e as suas Features são listadas a partir do catálogo, como as de todos os diretórios de catálogo configurados. As Features listadas a partir dos diretórios de catálogo nunca incluem uma por trás de uma ligação que conduza para fora do diretório dentro do qual as leituras de um diretório de catálogo têm de ficar — o espaço de trabalho, para um diretório de catálogo dentro dele, ou o próprio diretório, para um que a configuração nomeia fora dele — pelo que uma entidade que a resposta nomeia como estando por trás de uma ligação que não leu nunca é também listada ao lado desse nome. A resposta nomeia cada uma dessas ligações emunreadLinkedDirs, para uma ligação para um diretório, e emunreadLinkedFiles, para uma ligação cujo próprio nome termina em.yamlou.ymle que conduz a um ficheiro — relativas à raiz, onde a ligação se encontra, pela ordem em que o espaço de trabalho é pesquisado — para que um cliente possa explicar porquê. Uma ligação que a pesquisa deixa de fora, pelo seu nome, pelo sítio onde se encontra ou por um.gitignore, não é nomeada, e numa resposta nos termos de uma Release também não o é uma que esteja sob um diretório de catálogo que só outras Releases leem. Uma ligação sob um diretório de catálogo fora do espaço de trabalho não tem lugar relativo à raiz onde possa ser nomeada, e não é nomeada. Ambos estão sempre presentes, e vazios quando não há nenhuma ligação dessas. Onde o próprio ficheiro de configuração do espaço de trabalho, ou a sobreposição gerida pela CI ao seu lado, é ele próprio uma ligação que conduz para fora do espaço de trabalho, esse ficheiro é nomeado emunreadLinkedFiles, seja qual for a forma como a pesquisa o trata, e o índice é a leitura do próprio espaço de trabalho sem nada configurado — nenhum diretório de catálogo é lido para ele, e um índice nos termos de uma Release é recusado; consulte Raiz do espaço de trabalho e Release ativa.aggrega/entityDefinition— aquilo para que a entidade nomeada resolve: o seukind, o seu próprionameeversion, a suadescriptione o seupublishScopequando os tem, ofileem que foi declarada, oauthoredLengthdo texto escrito por trás dela e a suadefinitioncomo um documento YAML com a herança já aplicada.fileé reportado para todos os tipos, como um caminho que se pode abrir — relativo à raiz do espaço de trabalho para um documento dentro dele, absoluto para um fora dele, segundo Como é escrito um caminho reportado. Está vazio num caso: uma entidade resolvida a partir de um registo não tem nenhum documento escrito nesta máquina a nomear.authoredLengthresponde a uma pergunta diferente — quanto texto escrito a resolução reteve — e só um Aggregate é servido com algum, pelo que devem ser lidos separadamente e não como um par.nameé a identidade de uma entidade, escrita da forma como uma entidade referencia outra, e pode ter um sufixo de versão. Este é o único pedido aqui que parte de um nome e não de um cursor, pelo que é o que se deve pedir quando já se sabe a que entidade se refere.releaseé opcional e resolve o nome nos termos dessa Release — consulte Responder nos termos de uma Release. Um nome que não resolve para nada é recusado em vez de respondido com um documento vazio; consulte Distinguir as duas recusas por nome.namepode em vez disso ser uma referência de registo —oci://<host>/<repository>:<tag>, ou@<digest>no lugar de:<tag>— e a resposta é então a entidade publicada nessa coordenada, lida do seu registo, compublisheda nomear o que foi lido; consulte Perguntar sobre uma coordenada.aggrega/releaseClosure— o fecho de dependências de uma Release: que entidades alcança e em que versões resolvidas, ementities,librarieseplugins, juntamente com as identidadesaggregateemanifestpara que os seus dois ponteiros resolveram, quaisquermappingDiagnosticsque a resolução tenha levantado e asdeprecationsregistadas para aquilo que alcançou — no seu lockfile e no registo de confiança dos plugins ao lado dele, pelo que um plugin retirado anexado num papel de veredicto é nomeado tal como o é uma referência fixada retirada.releaseé um caminho relativo à raiz do espaço de trabalho que nomeia uma Release dentro dele, o mesmo valor queaggrega/irGraphaceita e recusado nas mesmas formas, e exige um lockfile pela mesma razão. Nada é renderizado. As suas entradas não nomeiam nenhumasource: dizem aquilo de que a Release depende, não o que uma execução fez, que é o queaggrega/resolveDependenciesreporta. Consulte Um fecho não é o grafo, porque um cliente que já recebe o grafo não tem isto.aggrega/attachCandidates— que Features podem ser anexadas a um nó: aquelas cuja aplicabilidade declarada as etiquetas do nó satisfazem. Envie exatamente uma coordenada.nodenomeia um documento do espaço de trabalho pelo seumetadata.name;graphNodenomeia um nó no grafo compilado derelease, pelo id sob o qual esse grafo o indexa;labelscontém diretamente um conjunto de etiquetas e não nomeia nada, para um cliente que já tenha um. A resposta repete a coordenada para a qual respondeu — vazia quando não havia nenhuma a repetir — contémnodeLabels, os pares de etiquetas em relação aos quais a correspondência foi avaliada,labelSource, que diz que tipo de conjunto de etiquetas são, e cada candidato como okind, oname, o ficheiro de origem e aoriginque o endereçam. Devolver as etiquetas é o que torna a resposta auditável por si só: um cliente pode explicar porque é que uma Feature foi oferecida sem formar a sua própria ideia das etiquetas do nó, que é como a resposta de um cliente e a do compilador divergem. Para um nó do grafo, as Features em oferta são as que a Release desse nó alcança. Ao lado degraphNode,connectionnomeia uma ligação que o componente desse nó estabelece — o seusocketealias— e a resposta contém então tambémslots, cada slot que o socket dessa ligação declara com as Features que o podem preencher, ounoSlotReasononde nenhum pode ser preenchido. Consulte O que uma resposta de candidatos a anexo indica.aggrega/connectionCandidates— a que se pode ligar a entidade nomeada.nodeé ometadata.namede uma entidade, a mesma coordenada queaggrega/attachCandidatesaceita sob esse nome. Consulte O que uma resposta de candidatos a ligação indica abaixo, porque as duas metades da resposta não são igualmente completas e a resposta diz qual é qual.aggrega/insertionPoint— onde, num documento escrito, pertence uma nova entrada sob um contentor nomeado, expresso de modo que um cliente a aplique sem analisar ele próprio o documento.filenomeia um documento que o espaço de trabalho contém, relativo à raiz do espaço de trabalho, absoluto ou como o seu endereçofile://; um documento fora da raiz, tal como está escrito ou através de uma ligação que conduza para fora dela — até ao ficheiro ou até um diretório pelo caminho — é recusado, seja qual for a grafia que o nomeia e quer se tenha uma cópia dele quer não;containeré o caminho estrutural desde a raiz do documento até ao contentor dentro do qual vai a entrada, cada elemento uma chave de mapeamento ou uma posição de sequência escrita em decimal. O utilizador fornece esse caminho — o daemon lê a própria estrutura do documento e nunca deduz onde algo pertence a partir do seu nome. Consulte O que uma resposta de ponto de inserção indica, porque a posição por si só não basta para aplicar a edição.aggrega/attachmentContainer— em que documento pertence um anexo de Feature para um nó, e em que contentor dentro dele.graphNodenomeia um nó no grafo compilado derelease, pelo id sob o qual esse grafo o indexa, e ambos são obrigatórios: um id de nó é uma chave do grafo de uma Release e não significa nada sem ela. A resposta contémnode,fileecontainer— uma lista de segmentos exatamente com a forma queaggrega/insertionPointaceita, pelo que o par se compõe sem nada a deduzir pelo meio. Para um anexo numa ligação que o componente do nó estabelece, acrescenteconnectioncom o seusocket,aliasedocument—aggregateourelease— e a resposta nomeia o próprio contentorfeaturesdessa ligação nesse documento. Consulte O que uma resposta de contentor de anexo indica, porquefilefaz parte da resposta e não é algo que já se saiba.aggrega/connectionAtPosition— dentro da entrada de que ligação cai uma posição num Aggregate ou numa Release, respondido nos termos em que os dois pedidos acima aceitam uma ligação.filenomeia o documento comoaggrega/insertionPointnomeia um, e é lido primeiro a partir do que a sessão contém para ele;positioné o lugar nele, umalinee umcharactercontados a partir de zero na codificação da sessão;releasenomeia a Release cujo grafo compilado regista as ligações, e é obrigatório também para uma posição no Aggregate, porque um nó do grafo e uma ligação só existem num grafo compilado. A resposta contémgraphNodeeconnection— o seusocket, o seualiase odocumentem que a posição foi lida — para entregar aaggrega/attachCandidateseaggrega/attachmentContainersem alterações, ounoConnectionReasononde não está escrita nenhuma ligação. Consulte O que uma resposta de ligação numa posição indica.aggrega/editDocument— aplicar uma edição estruturada e delimitada a um documento escrito, preservando todos os bytes em que não toca. É a outra metade dos dois métodos de localização acima: esses dizem onde pertence uma entrada e deixam ao utilizador compô-la e aplicá-la, este compõe e aplica uma.editnomeia qual de quatro —add-component,attach-feature,wire-edge,set-value— e um valor fora destes é recusado em vez de interpretado;nodeé o caminho estrutural desde a raiz do documento, uma lista de segmentos exatamente com a forma queaggrega/insertionPointaceita;nameé a chave sob a qual a entrada é escrita evalueo que contém, cujo significado decorre deedit;socketé lido parawire-edgee ignorado nos outros casos.dryRunfaz tudo o que o pedido simples faz exceto escrever, respondendo com o documento editado comocontent, para um cliente que coloca primeiro o resultado diante do autor; nada é criado com ele ewrittenestá vazio.filenomeia o documento relativamente à raiz do espaço de trabalho ou pelo seu caminho absoluto, e um documento fora da raiz — tal como está escrito, ou através de uma ligação que conduza para fora dela, até ao ficheiro ou até um diretório pelo caminho — é recusado sem nada lido nem escrito. Isto escreve o documento nomeado, dentro do espaço de trabalho — não resolve nenhuma dependência, não alcança nenhum registo e não toca em nenhuma rede em nenhum dos modos de entrega, e a escrita está condicionada a que o documento composto seja validado em relação ao esquema do seu próprio tipo. Consulte O que uma resposta de edição de documento indica, porque a predefinição é a escrita e uma recusa deixa o ficheiro exatamente como estava, byte a byte.aggrega/releaseCandidates— os documentos de Release do espaço de trabalho que o pedido nomeou, como caminhos absolutos. Aceita o espaço de trabalho e mais nada: o conjunto é uma propriedade dessa raiz de espaço de trabalho. A pertença é decidida pelo tipo de documento — okind:do ficheiro éRelease— e não pelo nome do ficheiro, pelo que uma Release com um nome sem prefixo convencional é oferecida e um ficheiro que apenas tenha um nome parecido não o é. Isto é o que o seletor «que Release?» de um editor deve listar, porque é o mesmo conjunto entre o qual a cascata de Release ativa abaixo escolhe. A resposta contém tambémlockfiles, que associa cada Release listada — indexada exatamente pela cadeia sob a qualreleasesa lista — ao caminho absoluto do seu lockfile; está sempre presente, e é um objeto vazio quando o espaço de trabalho não contém nenhuma Release. Contém tambémunreadLinkedDirs, que nomeia — relativamente à raiz, onde a ligação se encontra — cada ligação que está onde a listagem leria um diretório e que conduz a um diretório fora da raiz do espaço de trabalho: nenhum diretório fora da raiz é pesquisado, pelo que uma Release que o editor mostre dentro de um deles não é listada, e este campo é o que permite a um seletor explicar porquê. Uma ligação para um diretório que a configuração do espaço de trabalho lista sobcatalog_dirsnão é nomeada: a configuração alcançou-o, como diretório de catálogo e não como um sítio onde se guardam Releases. Está sempre presente, e vazio quando não há nenhuma ligação dessas. Ao seu lado,unreadLinkedFilesnomeia da mesma forma cada ligação cujo próprio nome termina em.yamlou.ymle que conduz a um ficheiro fora da raiz do espaço de trabalho: nenhum ficheiro desses é lido, seja o que for que contenha, pelo que uma Release alcançada apenas através de uma dessas ligações não é listada, e o passo de Release única da cascata abaixo não a conta. A exceção é um ficheiro que a configuração do espaço de trabalho nomeia como Release — comobuild.authoring_release, ou como chave deworkspace.releases, avaliado pelo ficheiro a que a ligação conduz, pelo que nomear a ligação ou esse ficheiro conta da mesma forma — que é lido e listado no próprio lugar da ligação, e não é nomeado, desde que declare uma Release; um que declare outra coisa não é listado, e a sua ligação é nomeada. Está sempre presente, e vazio quando não há nenhuma ligação dessas. Onde o próprio ficheiro de configuração do espaço de trabalho, ou a sobreposição gerida pela CI ao seu lado, é ele próprio uma ligação que conduz para fora do espaço de trabalho, esse ficheiro é nomeado aqui, seja qual for a forma como a pesquisa o trata, e a listagem é lida sem nada configurado, pelo que uma Release que a configuração teria nomeado através de uma ligação não é listada; consulte Raiz do espaço de trabalho e Release ativa. Consulte Onde está o lockfile de uma Release.aggrega/activeRelease— para que Release aponta o espaço de trabalho que o pedido nomeou, como caminho absoluto num camporelease, para um cliente que decide o que selecionar por predefinição. Aceita o espaço de trabalho e mais nada. O campo está sempre presente, e um valor vazio significa que o espaço de trabalho não aponta para nenhuma — uma resposta bem-sucedida e não um erro, pelo que um cliente que atualiza isto em cada reinício do daemon não é obrigado a tratar um espaço de trabalho normal como uma falha. Quando o valor está vazio, a resposta contém tambémreason, um resumo numa linha do que a cascata procurou, etrace, o relato passo a passo disso; ambos são omitidos quando uma Release foi resolvida. Quando uma Release foi resolvida, a resposta contém em vez dissolockfile, o caminho absoluto do lockfile dessa Release, que é omitido quando nenhuma o foi. A Release que nomeia não tem de ser uma queaggrega/releaseCandidatesliste — um marcador pode nomear uma Release num diretório que essa listagem deixa de fora, comovendor/, ou uma nomeada sem extensão YAML — pelo que esta resposta é onde um cliente lê o lockfile da Release predefinida. Consulte Onde está o lockfile de uma Release. Peça-a em vez de deduzir a resposta a partir de uma das entradas da cascata: uma entrada que a cascata acabou por não usar nomeia uma Release diferente da que escolheu. A resposta é calculada no momento do pedido, pelo que perguntar de novo depois de escrever um marcador, editar a configuração ou acrescentar um ficheiro de Release reporta a nova resposta e não o espaço de trabalho tal como estava quando o daemon arrancou.aggrega/setActiveRelease— regista uma Release como a predefinida do espaço de trabalho que o pedido nomeou, escrevendo o marcador.aggrega/active-releasedesse espaço de trabalho, e responde exatamente comoaggrega/activeReleaseresponde depois de o marcador ser escrito. Aceita o espaço de trabalho erelease: um caminho relativo à raiz do espaço de trabalho que nomeia uma Release dentro dele, sujeito ao mesmo contrato a que está sujeita areleasedeaggrega/irGraph— um caminho absoluto, um que saia do espaço de trabalho e um valor vazio são recusados, e o mesmo acontece a um que conduza para fora através de uma ligação, a menos que a configuração do espaço de trabalho nomeie essa Release. O marcador é uma linha que nomeia a Release relativamente à raiz, a forma que a cascata abaixo lê. É escrito dentro do espaço de trabalho e em mais lado nenhum: onde.aggrega, ou o próprio marcador, é uma ligação que conduz para fora do espaço de trabalho — quer o sítio a que conduz já exista quer não — o pedido é recusado com o erro de parâmetros inválidos, com a mensagem a ser a própria frase da condição precedida do seu código curto,E0320: …(fatal-halts.md §“A path the operation writes leads through a link out of the directory it must stay inside (Um caminho que a operação escreve conduz, através de uma ligação, para fora do diretório dentro do qual tem de ficar)”), nomeando a ligação e para onde conduz, e nada é escrito; uma ligação que fique dentro do espaço de trabalho é seguida na escrita. A resposta nomeia aquilo em que a cascata se fixa em vez de ecoar o que foi enviado, e os dois diferem ondebuild.authoring_releasenomeia uma Release, já que a configuração tem prioridade sobre o marcador. Registe uma predefinição desta forma em vez de escrever o ficheiro manualmente, para que o sítio onde o marcador fica seja avaliado pela regra a que está sujeito todo o ficheiro que o produto escreve no espaço de trabalho — consulte A fronteira do espaço de trabalho.aggrega/effectiveConfiguration— a configuração em vigor para o espaço de trabalho que o pedido nomeou, e a camada de onde veio cada definição. Aceita o espaço de trabalho e mais nada: a resposta é uma propriedade desse espaço de trabalho.layerslista os ficheiros de configuração e as substituições do ambiente que contribuíram, da menor precedência para a maior;settingscontém cada definição atribuída como o seu nome com pontos, o seu valor efetivo e asourceque o determinou. Umasourceé escrita exatamente como a entrada correspondente emlayers, pelo que as duas se juntam diretamente. Consulte O que abrange a resposta de configuração efetiva para a camada que umasourcenomeia e os limites do significado de uma linha.aggrega/configInit— semeia uma configuração funcional, registando um registo e a respetiva política de confiança de assinaturas, para que uma máquina nova possa obter e verificar artefactos assinados sem editar YAML à mão.registryé opcional e um valor ausente semeia o hub oficial, a mesma predefinição queaggrega config initusa; ohostda resposta indica qual foi usado.globaleworkspacesão as substituições do destino de escrita, e enviar ambos é recusado. Recusa em vez de sobrescrever um ficheiro de configuração existente, indicando o ficheiro — envieforcepara prosseguir mesmo assim, o que funde a entrada do registo no que já existe e preserva as restantes definições.dryRunfaz tudo o que o pedido simples faz exceto escrever, respondendo com a configuração semeada comocontent, para um cliente que coloca o documento diante do autor antes de ser guardado; nada é criado com ele ewrittené false. A recusa por ficheiro existente aplica-se também comdryRun, pelo que deve enviarforcejuntamente para obter como resposta a fusão que uma escrita com sobrescrita produziria. Num espaço de trabalho offline só o hub oficial pode ser semeado: este pedido não recebe identidades nem chave, pelo que qualquer outro registo é recusado exatamente comoaggrega/registryAddo recusa, código curto e frase incluídos, e é adicionado através desse pedido com uma política fornecida à mão. A resposta contémhost,scope,trustewritten, eexisted, verdadeiro quando o ficheiro de configuração já existia — de modo que a entrada do registo é fundida nele em vez de ser criado um ficheiro novo — e ausente quando o ficheiro é criado. Isto escreve a configuração global por predefinição — consulte Aceder a um registo e escrever.aggrega/configCapture— congela a configuração efetiva crítica para a compilação no ficheiro de configuração do próprio espaço de trabalho, para que o espaço de trabalho compile da mesma forma sem a configuração global da máquina por baixo. Não recebe destino de escrita: congelar existe para tornar um espaço de trabalho autossuficiente, pelo que escreve sempre o ficheiro desse espaço de trabalho.allPluginsalarga o conjunto congelado, dos sockets que determinam o resultado renderizado — as associações de fornecedor e os anexos de governação que transformam etiquetas — a todos os sockets de plugin, acrescentando as barreiras de veredicto de governação e de linter e o socket de importação. A resposta contémconfigFile,workspaceRoot,captured,socketsecatalogDirs. Consulte O que uma escrita de configuração deixa para trás, porque a resposta indica um documento que agora existe e o ato seguinte de um cliente é abri-lo.aggrega/skillsInstall— escrever a skill do Aggrega incorporada neste binário na pasta de skills de cada assistente que o pedido nomeia, a mesma instalação queaggrega skills installexecuta num terminal.agentslista os assistentes por identificador, os identificadores queaggrega/skillsListreporta; um identificador dado duas vezes é instalado uma vez, e onde vários dos assistentes nomeados leem uma mesma pasta partilhada, a skill é escrita aí uma vez. Uma instalação de projeto exige-o. Um pedido comglobalque não nomeie nenhum instala para os assistentes encontrados nesta máquina, tal comoaggrega skills install --globalfaz sem--agent— cada um cuja pasta de configuração está no diretório pessoal, ou cujo comando está noPATHdo ambiente do daemon — e é recusado sem nada escrito quando nenhum é encontrado; nada é perguntado, einstallednomeia os assistentes para os quais escreveu. Semglobal, a skill fica na pasta de projeto de cada assistente dentro do espaço de trabalho que o pedido nomeia, nunca no diretório em que o daemon foi iniciado; comglobal: true, fica na pasta por utilizador de cada assistente sob o diretório pessoal que o ambiente do daemon nomeia (HOME, ouUSERPROFILEno Windows). Cada destino é verificado antes de qualquer escrita, pelo que uma recusa deixa todas as pastas como estavam: um identificador para o qual não se conhece nenhuma pasta de skills é recusado, nomeando-o e os identificadores existentes, e um ficheiro num destino que não contenha a linha de comentário que todas as cópias escritas da skill contêm é recusado, nomeando o seu caminho. Uma cópia que contenha essa linha — uma que uma instalação anterior escreveu, ou uma retirada do repositório de skills publicado — é substituída, e é assim que umaggregamais recente atualiza a skill para a sua própria versão. Uma pasta de projeto alcançada através de uma ligação que conduz para fora do espaço de trabalho é recusada sem nada escrito, como todas as escritas que o daemon faz num espaço de trabalho — consulte A fronteira do espaço de trabalho. A resposta contémskill,installed— uma entrada por pasta escrita, pela ordem em que os assistentes foram nomeados, cada uma com osagentsque a leem, afolderabsoluta ereplaced— escope. Comglobal, isto escreve pastas que todos os projetos da máquina leem — consulte Alcançar um registo, e escrever.aggrega/skillsList— as skills que este binário inclui e todos os assistentes para os quaisaggrega/skillsInstallas pode escrever, a listagem queaggrega skills listimprime. Aceita o espaço de trabalho e nada mais, e não lê nada dele.skillscontém onamee adescriptionde cada skill;agentscontém oid, onamee aprojectFolderde cada assistente — relativa à raiz de um projeto, que nesta superfície é o espaço de trabalho que um pedido nomeia — e auserFolder, relativa ao diretório pessoal, ambas separadas por barras, ordenadas por identificador. Não escreve nada e não alcança nada.aggrega/pluginAdd— procura no registo configurado um plugin de um tipo indicado e adiciona-o à configuração.typeequerysão ambos obrigatórios:typeé um deprovider,governance,linter,importerecli, equeryé comparado com os nomes dos plugins desse tipo e tem de resolver para exatamente um, pelo que uma consulta que corresponda a vários é recusada com os candidatos em vez de ser resolvida arbitrariamente.capabilityindica a capacidade que uma associaçãoproviderserve e é aí obrigatório;roleindica a função de um anexogovernance—label-transform,ir-verdictourender-verdict— e é aí obrigatório; cada um é lido apenas para o seu próprio tipo e recusado em qualquer outro, porque um campo que silenciosamente não fizesse nada pareceria ter funcionado.acceptCapabilitiesé obrigatório paraclie confirma as capacidades declaradas desse plugin: o comando de terminal obtém essa decisão perguntando, e esta superfície não tem a quem perguntar, pelo que é quem chama que a obtém e a envia.globaleworkspacesão as substituições do destino de escrita e enviar ambos é recusado.dryRunfaz tudo o que o pedido simples faz exceto escrever, respondendo com a configuração resultante comocontent; nada é criado nem modificado ewrittené false. O registo continua a ser consultado e a versão continua a ser resolvida, porque a identidade nesse conteúdo é a identidade que uma escrita teria fixado.dryRuné recusado no tipocli, em vez de ignorado: o que uma adição de extensão de comando guarda é o digest de conteúdo dos bytes que verificou, que é um dado que o compilador mantém e não conteúdo que alguém edita, e a adição coloca esses bytes em cache à medida que avança — por isso é escrito em vez de devolvido. A versão é fixada por si — a consulta resolve para um plugin, e a versão que esta indica como<name>:<version>ou, caso contrário, a versão publicada mais alta do plugin é escrita na entrada; uma versão indicada que uma retratação em que este espaço de trabalho confia retirou é fixada mesmo assim, e a resposta incluiwithdrawn: true. Isto acede a um registo, e uma adição do tipoclique não indique nenhum âmbito escreve a configuração global — consulte Aceder a um registo e escrever. Consulte O que uma alteração de plugin lhe diz.aggrega/pluginRemove— remove a entrada de um plugin configurado para que deixe de participar.typeé o mesmo conjunto que uma adição recebe, equeryidentifica a entrada: o nome curto do plugin, a sua referência fixada ou — paraprovider— a capacidade que a associação serve. Ambos são obrigatórios.globaleworkspacesão as mesmas substituições do destino de escrita, recusadas em conjunto da mesma forma. Uma consulta que não corresponda a nenhuma entrada é recusada em vez de respondida como sucesso sobre uma configuração inalterada, de modo que quem chama nunca é informado de que um plugin deixou de participar quando tal não aconteceu, e um erro de escrita nunca remove um plugin diferente. Não contacta nenhum registo: uma remoção opera apenas sobre o texto da configuração. Uma remoção do tipoclique não indique nenhum âmbito escreve a configuração global — consulte Aceder a um registo e escrever. Consulte O que uma alteração de plugin lhe diz.aggrega/pluginSync— alinha os dados mantidos pela máquina de uma entidade Plugin com o seu módulo: o conjunto de funções de host derivado das importações do próprio módulo e o espelho de comandos lido do autorrelato do módulo. Nenhum destes dados é escrito à mão, porque ambos são a verdade de referência no módulo. Ambos os campos são obrigatórios e nenhum tem predefinição — os dados são derivados do módulo, pelo que um alinhamento que não indique nenhum não tem a que se alinhar — e ambos são caminhos relativos à raiz do espaço de trabalho, recusados quando absolutos ou quando resolvem para fora dela, tal como escritos ou através de uma ligação simbólica. Só esses dois blocos mudam: todos os outros bytes passam literalmente, incluindo comentários, linhas em branco e estilo de aspas, e um ficheiro que já regista o que o módulo implica é deixado idêntico byte a byte e reportado como inalterado. Isto escreve o ficheiro de entidade que indicar, dentro do espaço de trabalho, e não contacta nenhum registo. Consulte O que uma alteração de plugin lhe diz.aggrega/pluginGenCatalog— gera uma entidade Plugin por cada módulo convidado selecionado, fundindo os campos de contrato derivados do autorrelato do convidado com uma sobreposição escrita por plugin.fromEmbeddedepluginsão os dois modos de seleção e aplica-se exatamente um: todos os convidados que este binário transporta, ou um módulo num caminho que indicar; indicar ambos, ou nenhum, é recusado em vez de resolvido.overlayé obrigatório, e é um diretório de sobreposições comfromEmbeddedou um único ficheiro de sobreposição complugin— uma sobreposição é associada a um convidado pela identidade quando há vários, e não há nada a associar quando há um.outputDiré obrigatório em ambos os modos de entrega, edryRunnão o dispensa: uma execução de ensaio muda para onde vai o conteúdo, não para que ficheiro é esse conteúdo, pelo que cada documento devolvido continua a indicar o caminho a que se destina e esse caminho é composto a partir deste diretório. Os três caminhos aqui não são avaliados da mesma forma, e a divisão segue o que a geração faz com cada um.plugineoverlaysão lidos, e ambos são ficheiros que selecionou — um módulo fica em qualquer diretório para onde a sua cadeia de ferramentas compila, e a sua sobreposição é escrita ao lado dele — pelo que cada um pode ser absoluto e é lido onde realmente está.outputDiré escrito, pelo que é relativo à raiz do espaço de trabalho e recusado quando absoluto ou quando resolve para fora dela, tal como escrito ou através de uma ligação simbólica — um diretório ainda não criado sob um diretório ligado que conduz para fora é recusado tal como esse diretório. Executar de novo sobre entradas inalteradas produz entidades idênticas byte a byte. Isto escreve as entidades geradas emoutputDir, dentro do espaço de trabalho, a menos quedryRunas peça como conteúdo. Consulte O que uma alteração de plugin lhe diz.aggrega/getSchema— o JSON Schema de um tipo de entidade ou de contrato, lido da cópia compilada no binário em execução.kindé o token de esquema em minúsculas com hífenes —component,aggregate,release,recipe,ir,wasm-provider, e assim por diante — e é opcional, porque seleciona qual de duas perguntas está a fazer. Indique um tipo e a resposta contémkindeschema, o esquema como documento JSON e não como uma cadeia que o contém. Não indique nenhum e a resposta contém, em vez disso,kindseentityKinds: que tipos pode indicar, em duas larguras.kindsé cada token que este binário aceita, pela mesma ordem em queaggrega get-schema --listos imprime.entityKindsé o conjunto mais restrito de que um autor escreve documentos, cada entrada contendo o tokenkinda enviar de volta, o valordocumentKindque vai no próprio campokind:do documento eacceptedBy, que diz se a validação de entidade única, a publicação e a inspeção por nome aceitam um documento desse tipo. Consulte Que tipos pode oferecer a um autor antes de construir um seletor a partir de qualquer um deles. A resposta do esquema e a enumeração nunca são combinadas, pelo que a pergunta respondida é legível a partir da resposta. Um token a que nenhum esquema corresponde é recusado com todo o conjunto válido na mensagem, para que um erro de escrita seja corrigido sem uma segunda chamada. Não usa nada do espaço de trabalho, não contacta nenhum registo e não escreve nada, pelo que responde num espaço de trabalho que não contém absolutamente nada — o que o torna utilizável para configurar a associação de esquemas de um editor com o binário que o editor está realmente a controlar, e não com qualquer cópia dos esquemas instalada noutro lado.aggrega/scaffoldEntity— um documento inicial para um tipo de entidade: exatamente os campos que o esquema desse tipo exige, comapiVersionekindfixos preenchidos e um marcador de posição em todo o lado onde é necessário um valor.kindé obrigatório e é o token de esquema em minúsculas com hífenes —component,aggregate,release,recipe,manifest,feature, e assim por diante;aggrega/getSchemasemkindindica que tokens pode enviar, e um token a que nenhum esquema corresponde é recusado com esse conjunto na mensagem, para que um erro de escrita seja corrigido sem uma segunda chamada. Um cliente que ofereça ao autor uma escolha de tipo lê oentityKindsdesse método, que é o conjunto de tipos de que se pode escrever um documento.nameé opcional e semeiametadata.namepara os tipos cujo esquema exige um. A resposta contémkindeskeleton. Consulte O que uma resposta de esqueleto lhe dá, porque a resposta é um documento a escrever e não um documento que foi escrito. O esqueleto é derivado do mesmo esquema queaggrega/getSchemareporta, pelo que ambos respondem a partir de uma única fonte. Quando recebeexampleem vez dekind, o método escreve um dos exemplos executáveis da documentação num novo diretório do espaço de trabalho, tal comoaggrega scaffold --examplefaz num terminal; quando recebe apenaslist: true, responde com todos os exemplos existentes e não escreve nada. As duas formas precisam do espaço de trabalho, pelo que um pedido de qualquer uma delas o nomeia emworkspaceRoot, e um que não nomeie nenhum é recusado.dirnomeia o novo diretório relativo à raiz do espaço de trabalho e, por predefinição, é o nome do exemplo; um valor absoluto, ou um que se resolva fora da raiz — tal como escrito, ou através de uma ligação — é recusado antes de qualquer leitura, e um diretório que contenha alguma coisa é recusado e deixado como está. A resposta a uma listagem contémexamples, cada um com o seuname,levelesummary; a resposta a uma escrita contémexample,dir,files— cada ficheiro escrito, relativo adir—,next, os comandos que a página do exemplo indica para o construir, ausente quando não indica nenhum, eversion, a versão da documentação a partir da qual o exemplo foi lido. Campos de duas formas enviados em conjunto —kindcomexample,listcomexampleoukind,namecomexampleoulist, oudirsemexample— são recusados antes de qualquer leitura, com as palavras com que a ferramenta do assistente os recusa. Uma escrita obtém o pacote de documentação quando a máquina não tem nenhuma cópia que a própria verificação de assinaturas do espaço de trabalho admita, e escreve dentro do espaço de trabalho — consulte Alcançar um registo, e escrever.aggrega/import— converte uma descrição de origem estrangeira em ficheiros de autoria Aggrega em rascunho, a mesma conversão queaggrega importefetua num terminal.sourceé obrigatório e indica o ficheiro ou o diretório a converter, seja como caminho absoluto, seja relativo à raiz do espaço de trabalho — uma descrição exportada por outra ferramenta está onde quer que a tenha guardado, pelo que esta é lida onde realmente está e não apenas dentro do espaço de trabalho. Um diretório é lido comoaggrega importlê um: para os ficheiros dele que os padrões de ficheiros declarados pelo importador selecionam, excluindo a pasta de saída de compilação do espaço de trabalho,dist/, e confinado a si próprio onde quer que esteja, pelo que nenhuma ligação simbólica dentro dele é seguida para fora dele.outputDiré opcional e indica o diretório para onde vão os rascunhos, e não segue esse contrato: é escrito, pelo que é um caminho dentro do espaço de trabalho, e um valor absoluto, ou um que resolva para fora da raiz — tal como escrito ou através de uma ligação simbólica, incluindo um diretório ainda não criado por baixo de uma — é recusado. Omita-o e os rascunhos vão para baixo da raiz do espaço de trabalho, ondeaggrega importos escreve quando não indica nenhum destino — também comdryRun.formatindica explicitamente o formato de origem; omita-o e o formato é reconhecido pelas assinaturas que os importadores declaram — tanto as do catálogo do espaço de trabalho como as dos importadores nucleares do compilador — e uma origem que nenhum reconheça, ou que importadores de mais de um formato reconheçam, é recusada pedindoformatem vez de ser adivinhada.targetindica uma capacidade de fornecedor, comocomposeouhelm— a palavra a que ospec.capabilityde uma Recipe se associa — e redige, ao lado dos rascunhos do importador, o Manifest com que a Release redigida compila para esse fornecedor, exatamente comoaggrega import --targetfaz:manifest.yaml, que mapeia cada tipo de componente e cada tipo de funcionalidade de que os rascunhos precisam — incluindo os tipos de um Aggregate do catálogo que o redigido compõe — para a Recipe ou a receita de funcionalidade dessa capacidade que o catálogo do espaço de trabalho oferece para ele, pelo seu nome qualificado pela capacidade sem versão: a única que existe ou, entre várias, a que tem o nome do tipo. Ospec.manifestda Release é definido para ele; um tipo sem nenhuma, ou com várias e nenhuma com esse nome, fica por mapear com uma constataçãowarnque o indica, e um mapeamento que o próprio importador redigiu é mantido onde o catálogo o oferece para esse tipo e essa capacidade, e descartado com uma constataçãowarncaso contrário. Umtargeta que nenhuma Recipe do catálogo se associa é recusado antes de o importador ser executado, indicando-o e as capacidades a que as Recipes do catálogo se associam, e nada é escrito; omita-o e nenhum Manifest é redigido — exceto comsync, que redige para o destino que o histórico da importação anterior indica. Um importador nuclear que a máquina ainda não tem é obtido pela primeira importação que dele precisa — consulte O que uma resposta de importação lhe diz.dryRunfaz tudo o que o pedido simples faz exceto escrever, respondendo com os rascunhos como conteúdo, para um cliente que os coloca primeiro diante do autor; nada é criado com ele ewrittenfica vazio.syncatualiza o que uma importação anterior redigiu emoutputDirem relação à origem, alterando apenas o que a importação escreveu, comoaggrega import --syncfaz; sem ele, um pedido cujos rascunhos seriam escritos por cima de um Aggregate já existente é recusado. A resposta contémformat,outputDir,written,files,drift,diagnostics,decisionsehalted. Consulte O que uma resposta de importação lhe diz, porque uma origem que o importador não conseguiu converter totalmente é uma resposta bem-sucedida e não um erro.aggrega/explainError— o que o compilador declara sobre a condição que um código indica, e as entradas publicadas que ensinam a correção de autoria.codeé obrigatório e aceita qualquer um dos identificadores de uma condição: o código curto que um diagnóstico contém emshortCode, ou o descritivo emcode. É a expansão de um código que os diagnósticos neste protocolo já contêm, e é a mesma resposta queaggrega explainimprime num terminal. A resposta contém sempre a condição —shortCode,codeemessage— porque isso está declarado dentro do binário e não precisa de rede;entriescontém o passo a passo publicado, enotediz porque falta quando falta. Isto adquire o pacote de documentação quando a máquina não tem nenhuma cópia que a própria verificação de assinaturas do espaço de trabalho admita — consulte Aceder a um registo e escrever. Consulte Expandir um código que um diagnóstico continha.aggrega/invalidate— um sinal de invalidação da cache vindo do observador de ficheiros do editor.
Notificações:
$/cancelRequest— do cliente para o servidor: interrompe o pedido em curso enviado com esse id. O daemon cancela o trabalho desse pedido; uma operação observa o cancelamento no limite do passo seguinte e não instantaneamente, pelo que o trabalho já em curso continua por um momento. Cancelar um id em que nada está a ser executado é uma operação nula segura.$/progress— do servidor para o cliente: o que uma operação longa está a fazer enquanto o faz, no token em que o pedido pediu que fosse reportado. Enviado apenas para um pedido que tenha incluído um. Consulte Acompanhar uma operação longa.aggrega/shutdown— inicia um esvaziamento cooperativo: os pedidos em curso terminam, os novos pedidos são recusados e depois o daemon termina.aggrega/publishDiagnostics— um conjunto de diagnósticos enviado pelo servidor (usado para avisos de desvio do lockfile e para o estado no arranque). Cada entrada contém umsourceque indica qual das camadas de diagnóstico do daemon a levantou:aggregapara uma constatação sobre os documentos de autoria,aggrega-buildpara um aviso consultivo que uma compilação levantou — todos os avisos que levantou, que é o mesmo conjunto queaggrega buildimprime — eaggrega-lintpara uma constatação sobre convenções de publicação, as mesmas constatações queaggrega lintimprime. O campo está sempre presente em todas as entradas, para que um cliente as possa agrupar em vez de mostrar uma única lista indiferenciada, e nunca tenha de distinguir uma origem ausente de uma das camadas. Uma trama é enviada para um ficheiro apenas quando o seu conjunto difere daquele de que este cliente foi informado pela última vez, pelo que um pedido que recalcula as mesmas constatações não envia nada; a primeira trama de um ficheiro, e uma trama que esvazia o conjunto de um ficheiro, são ambas diferenças e são sempre enviadas.
Pedir ao próprio processo que pare chega ao daemon nas mesmas condições. Uma interrupção a partir de um terminal, ou um pedido de terminação de um supervisor ou de um runtime de contentores, inicia o esvaziamento que aggrega/shutdown inicia: os pedidos em curso terminam, os novos pedidos são recusados e depois o daemon termina. Um segundo pedido termina o processo de imediato. Um cliente que lance o daemon pode pará-lo de qualquer uma das formas, e um que o pare pelo protocolo e um que lhe envie um sinal obtêm o mesmo esvaziamento.
Validação em tempo real
Em cada aggrega/validate o daemon valida o buffer do editor com o esquema do documento e devolve diagnósticos apontados à chave infratora — o mesmo veredicto que uma compilação daria, sobre conteúdo não guardado. Um pedido que não envia content pergunta pelo ficheiro tal como está no disco; um content enviado vazio é um buffer vazio, não um pedido pelo ficheiro. Um ficheiro enviado sem o seu conteúdo tem de ser um que o espaço de trabalho contém e que possa ser lido — um ficheiro fora do espaço de trabalho, um alcançado através de uma ligação simbólica que conduz para fora dele, ou um que não existe é recusado com o código invalid-params. Entidades de catálogo, Aggregates, Manifests e Releases são reconhecidos pelo seu apiVersion e kind. Os dois documentos que não têm tal cabeçalho — a configuração do espaço de trabalho .aggrega-config.yaml e o lockfile da Release que o pedido indicou — são reconhecidos pelo nome do ficheiro, pelo que uma chave inválida ou mal formada em qualquer um deles também é sublinhada em tempo real. Ficheiros que não são documentos Aggrega — modelos de charts Helm, ficheiros Compose, manifestos Kubernetes e ficheiros .lock de outros ecossistemas como Cargo.lock ou flake.lock — não recebem diagnósticos; o daemon nunca reporta sobre ficheiros estrangeiros.
Um marcador de posição ainda em falta é indicado na sua chave, com o que aceita. Uma entidade de catálogo de um tipo que aggrega validate verifica como entidade única é também lida quanto aos valores obrigatórios que deixa como cadeia vazia, pela leitura que esse comando aplica, pelo que o daemon indica cada marcador de posição que o comando indica para os mesmos bytes. Cada marcador de posição é uma entrada: o seu message diz que a chave é um marcador de posição ainda em falta, o seu suggest diz o que o valor aceita e o seu keyPath contém o caminho com pontos da chave. A entrada substitui a constatação do próprio esquema para esse valor vazio, e todas as outras constatações sobre o documento são reportadas tal como a verificação de esquema as reporta. Um marcador de posição que o esquema admite vazio também é indicado, embora a verificação de esquema não reporte nada sobre ele — o capability e o implements de uma Recipe ou de uma FeatureRecipe redigida são os que vai encontrar. Quando a verificação de esquema também recusa o documento, cada entrada contém o código dessa verificação, E0215, e quando o aceita as entradas não contêm código: os mesmos identificadores que o relatório do comando contém para esses bytes. Uma entrada é desenhada na chave que contém o valor vazio, na linha em que o comando a indica — mesmo uma chave cujo próprio nome contém um ponto, como a etiqueta component.aggrega.ai/type, em que uma constatação que a verificação de esquema reporta sobre essa chave é desenhada na chave que a envolve — e keyPath indica a chave por completo. Isto verifica-se quer o pedido indique uma Release quer não, porque é uma pergunta a que o documento responde por si só, e um documento que ainda deve um valor ainda não é um sobre o qual se perguntem as convenções de publicação: essa camada é limpa para ele, tal como para um documento cuja forma o esquema recusa.
Cada pedido indica a Release a que se refere, e o daemon não mantém nenhuma própria. As verificações semânticas resolvem o fecho de dependências dessa Release e leem o lockfile dessa Release para obter as suas fixações — ou, para uma entidade de catálogo, leem os diretórios de catálogo com que essa Release compila, como descreve o parágrafo seguinte — pelo que dois pedidos que indiquem duas Releases são respondidos sobre a Release que cada um indicou. Nada transita entre eles: não há Release selecionada a mudar, e mudar a Release com que se valida é um valor diferente no pedido seguinte, e não algo que o daemon tenha de ser instruído a esquecer.
Uma entidade de catálogo indicada com uma Release é verificada como entidade única, nos termos dessa Release. Um file que contenha um Component, uma Feature, uma Recipe, uma FeatureRecipe ou um Plugin, enviado com uma release, recebe a verificação que aggrega validate <path> --release <release> executa, sobre o buffer não guardado do editor: as suas referências — o Component que uma Recipe implementa, uma biblioteca a que um pilar se refere — resolvem através dos diretórios de catálogo que a configuração do espaço de trabalho dá a essa Release, pelo que um ficheiro pode estar limpo nos termos da Release que compila com ele e falhar nos termos de uma Release cujos diretórios não contêm aquilo a que se refere. Esse é o veredicto que a linha de comandos e a ferramenta validate de aggrega mcp dão para a mesma entidade ao lado da mesma Release e, tal como o delas, não percorre nenhum fecho nem lê nenhum lockfile. Uma constatação bloqueante é uma entrada de erro nas palavras da própria verificação e com os seus códigos, desenhada na chave que indica na entidade e, quando não indica nenhuma, na chave kind: da entidade, como descreve O que contém uma entrada de diagnóstico — a menos que uma compilação já reporte essa falha no ficheiro, caso em que a entrada da compilação é o único relatório; um aviso consultivo que a verificação levanta ao ler o catálogo é uma entrada de aviso antes dela; uma verificação limpa sobre diretórios que existem todos não dá nenhuma entrada. Uma asserção falhada — uma que chama fail, na Recipe ou no Component que implementa — não é aqui uma constatação bloqueante, mas uma entrada de aviso, nas palavras da verificação e com os seus códigos, terminada pela frase A Release must satisfy this assertion before a build of it can pass., e desenhada onde estaria a constatação bloqueante: a asserção de uma Recipe na própria chave dessa asserção em assertions, a de um Component na chave kind: da Recipe. Tal como uma constatação bloqueante, cede o lugar à entrada de uma compilação que reporte a mesma falha no ficheiro. A verificação constrói a entidade em torno de marcadores de posição e predefinições do esquema e não dos valores que uma Release define, pelo que não consegue distinguir uma asserção que espera por uma Release de uma que está avariada, e deixa o veredicto a uma compilação, que reporta a mesma asserção como erro (uma asserção falhada é um aviso). Um diretório que a configuração do espaço de trabalho lista para a Release e que não é um diretório — onde nada existe, por exemplo — interrompe a verificação: o ficheiro contém uma única entrada de erro em vez do veredicto da verificação, a recusa que todos os comandos dão a esse diretório, indicando a entrada, o ficheiro de configuração e a linha que a lista, e a definição (De onde são lidas as entidades locais). Uma release que não indique nenhum ficheiro, ou que indique um diretório, é respondida no ficheiro com a frase com que a linha de comandos a recusa, em vez de ser verificada nos termos do espaço de trabalho. O que uma compilação de uma entidade não pode substituir é avaliado como a linha de comandos o avalia, e o que a linha de comandos põe de parte ou não verifica não dá aqui nenhuma entrada — consulte o que a correção de entidade única não verifica e, para uma Recipe cujo modelo lê um valor que só uma aresta da topologia ou uma credencial anexada fornece, correção de entidade única. O próprio Aggregate da Release, um Manifest, uma Release e uma biblioteca não são verificados um de cada vez, porque a verificação de entidade única não aceita esses tipos; mantêm as verificações do fecho acima. Um buffer que contenha conteúdo de Workload é lido como YAML que não é um documento Aggrega, porque esse conteúdo é escrito dentro do campo workload: de uma Recipe ou de uma FeatureRecipe e é verificado aí, onde está; a linha de comandos e a ferramenta validate, quando recebem um ficheiro de Workload por caminho, verificam a sua forma por si só.
Indicar uma Release é opcional, e a resposta diz qual das duas pediu. Indique uma e obtém tudo o que está acima. Não indique nenhuma e obtém as verificações a que um documento responde por si só — se é analisável, se a sua própria forma é admissível e, para uma entidade de catálogo de um tipo validado como entidade única, que marcadores de posição ainda deve — sem nenhuma Release resolvida, nenhum fecho percorrido e nenhum lockfile lido; a resposta contém então checked: "document". Indique uma Release e essa chave está ausente, porque essa resposta é o veredicto completo do método e não tem nada a ressalvar.
Leia a chave em vez de inferir a partir dos diagnósticos, porque as duas respostas podem parecer idênticas. Um documento bem formado validado sem Release responde com uma lista de diagnósticos vazia, que é exatamente aquilo com que um veredicto completo limpo responde, pelo que checked é a única coisa que separa «nada está errado» de «nada que precise de uma Release foi examinado». Uma consequência decorre da mesma regra: um lockfile é reconhecido pela sua correlação com a Release que o pedido indicou, pelo que um pedido que não indique nenhuma não reconhece nenhum lockfile e não reporta nada sobre ele.
Um espaço de trabalho que não contém nenhuma Release é respondido em vez de recusado, e é isso que mantém o resto do daemon utilizável aí. A validação é o que semeia a cache de análise que todas as outras operações sobre ficheiros leem, pelo que um repositório só de catálogo, um esqueleto de um único Aggregate ou um diretório de rascunho continuam a ter hover, completação, ir para a definição, referências, implementações e diagnósticos em cache. Recusar levaria tudo isso consigo, precisamente nos espaços de trabalho em que um cliente não tem nenhuma Release para indicar.
O que contém uma entrada de diagnóstico
Cada entrada posiciona-se com line e column, ambos com base 1 na codificação de posições negociada no handshake, e acrescenta end_line e end_column quando abrange um token inteiro. message é o texto que um cliente mostra ao utilizador, severity classifica-o e source indica qual das camadas do daemon o levantou, como descrito acima.
As camadas respondem a perguntas diferentes sobre um ficheiro, pelo que uma entrada de cada uma pode estar na mesma linha sem que nenhuma seja duplicado da outra: uma diz que a implantação não está correta, outra que a entidade não é publicável. Um cliente que as mostrasse como uma única lista reportaria um único problema duas vezes, e ler source é o que as separa.
Onde uma entrada fica depende daquilo a que se refere, não da camada que a levantou. Uma constatação sobre algo que o autor escreveu é posicionada na chave sob a qual o escreveu, para que o editor a desenhe onde a edição deve ser feita. Uma constatação sobre a forma da topologia implantada indica um componente e uma chave de entrega em vez de uma linha — são coordenadas na topologia implantada, não no documento — pelo que é desenhada na chave kind: do documento e indica as suas coordenadas na mensagem. Ambos os tipos chegam à camada aggrega-build, porque uma compilação levanta ambos. Uma recusa que uma compilação levantou durante a renderização também chega a essa camada, no documento para o qual a própria recusa aponta — um Workload que não satisfaz as suas verificações na chave workload da sua Recipe, a asserção falhada de uma Recipe na própria chave dessa asserção, uma entrada que a composição do grafo recusa na chave sob a qual a Release ou o Aggregate a escreveu, e cada constatação de uma recusa que junta várias no seu próprio documento e chave — e, quando não aponta para nenhum documento, na chave kind: do Aggregate; Uma recusa levantada durante a renderização descreve-a. Assim, um cliente posiciona cada entrada pelo seu próprio line e column e nunca infere uma posição a partir da camada.
Uma constatação que não indica nenhuma chave que o documento contenha é desenhada na chave que dá nome ao documento. Uma constatação que as próprias verificações de um documento levantam sobre o que ele diz, a constatação da verificação de entidade única, e um aviso consultivo ou uma recusa que uma compilação levanta são cada um desenhados na chave que indicam; quando não indicam nenhuma, ou indicam uma chave que o documento não contém, são desenhados na chave kind: do documento, ou no seu metadata.name quando não declara nenhum kind:, e no início do ficheiro apenas quando o documento não declara nenhum dos dois ou não é analisável. Um documento abre muitas vezes com um comentário — todos os ficheiros de catálogo têm um cabeçalho de licença — e uma entrada desenhada na sua primeira linha ficaria sobre esse comentário e pareceria uma falha nele, enquanto a própria identidade do documento é uma linha que o seu autor escreveu. Uma entrada sobre algo diferente do que o documento diz é colocada no início do ficheiro: uma entrada Dependencies: sobre as dependências da Release, uma fase que parou sem indicar nada no documento, um lockfile com desvio, uma referência que uma renderização teve de declinar, uma Release que não carregou — e também uma entrada aggrega-lint cuja regra não calculou nenhuma linha. Quando uma posição é declarada em vez de desenhada, uma constatação que não indica nenhuma chave continua a não ter nenhuma: a resposta de erro de uma recusa que não indica nenhuma chave contém apenas o documento no seu data.
Em que documento uma entrada é publicada decorre da mesma regra. Uma validação que indique uma Release responde ao Aggregate dessa Release, à própria Release, ao documento de cada módulo que o Aggregate importa e ao Manifest que a Release indica. Uma constatação posicionada na Release — uma recusa de uma entrada que a Release escreve numa das conexões de um componente, do dimensionamento que dá a essa conexão, de um anexo que aí preenche ou dimensiona, de uma conexão que liga, de uma Feature que só a Release anexa a um componente ou a uma fronteira, ou do infra que dá a um anexo — é publicada quando o documento da Release é validado, na chave da Release que a escreveu, e no Aggregate de forma nenhuma. Uma constatação posicionada no próprio documento de um módulo — uma recusa do que um dos componentes do módulo declara, de um socket que os seus anexos ligam, dos seus valores ou dos valores nas suas próprias conexões — é publicada quando o documento desse módulo é validado, na chave que aí a escreveu, e no Aggregate de forma nenhuma. Uma constatação sobre a tabela de mapeamento do Manifest — uma entrada que mapeia um tipo para uma Recipe ou FeatureRecipe que não o implementa, uma entrada cuja fixação de versão não pode ser analisada, ou um tipo mapeado cuja cadeia extends não pode ser seguida — é publicada quando esse Manifest é validado, na chave da entrada de mapeamento a que diz respeito, e no Aggregate de forma nenhuma; quando o texto aberto do Manifest não escreve essa entrada — uma entrada que herda através do seu próprio extends, ou uma que uma edição não guardada removeu —, a constatação é publicada na primeira linha do Manifest. Todas as outras constatações que a validação dessa Release levanta são publicadas no Aggregate, entre elas as constatações ao nível das dependências que não indicam nenhum documento do espaço de trabalho — uma referência ou um plugin retirado, um Component ou uma Feature de catálogo cuja cadeia extends não se resolve ou cujo esquema é inválido, um plugin de gate que não corresponde ao registo de confiança, uma instância de componente que nenhum mapeamento resolve, uma Recipe ou FeatureRecipe cujo fornecedor não consegue renderizar um tipo de entrada que declara, e os avisos de sobreposição de pilares de esquema e de estreitamento em extensão. Assim, uma constatação sobre o que o operador escreveu aparece enquanto a Release está aberta, uma sobre o que um módulo declara enquanto esse módulo está aberto, e uma sobre um mapeamento enquanto o Manifest está aberto, qualquer que seja a fase da compilação que a levantou; um editor que valida todos os documentos abertos com a Release mostra cada uma aí. Uma Release cujas dependências não podem ser resolvidas de todo não levanta nenhuma dessas constatações, e a falha em resolvê-las é uma entrada no início do próprio documento da Release e de todos os outros documentos validados com ela que o daemon reconhece, como descreve Validação em tempo real, e que não verifica como entidade única — o seu Aggregate, o seu Manifest, uma biblioteca, outra Release, a configuração do espaço de trabalho — prefixada com Dependencies: e contendo o relato da própria resolução sobre o que a impediu. No próprio documento da Release a entrada é esse relato e nada mais. Em todos os outros documentos começa por dizer que o documento é verificado com essa Release e indica a Release como um pedido a indica — Dependencies: this document is checked against the Release <release>, whose dependencies cannot be resolved: seguido do relato — porque nada nesse documento diz com que Release foi verificado: um editor que verifica todos os documentos abertos com a única Release selecionada coloca a entrada em documentos que nada têm a ver com essa Release, e o nome é o que lhe diz que a seleção é a causa. Um ficheiro que o daemon não reconhece não contém tal entrada, qualquer que seja a Release indicada com ele.
Uma resposta contém todas as camadas presentes no ficheiro, por mais longe que a validação tenha ido. A resposta de aggrega/validate é todo o estado atual do ficheiro: o que esta validação encontrou, as entradas aggrega-build que uma compilação, uma pré-visualização ou um pedido de grafo publicou no ficheiro, e as suas constatações sobre convenções de publicação, cada uma sob o seu próprio source. Uma validação que para no buffer — um que não é analisável, ou um documento cujo envelope o esquema recusa — responde da mesma forma: reporta a sua própria constatação e deixa todas as entradas de compilação no ficheiro, porque não aprendeu nada sobre a compilação. Assim, um cliente pode substituir o que tem para o ficheiro, camada a camada, a partir de qualquer resposta.
Uma falha é reportada uma vez. A validação própria de um documento e uma compilação podem encontrar a mesma falha nele: a verificação de entidade única renderiza uma Recipe que uma compilação também renderiza, a validação compõe o grafo que uma compilação compõe, e uma Release cujas dependências não resolvem faz falhar ambas. Enquanto uma compilação reporta tal falha num documento, a validação desse documento não a reporta uma segunda vez: uma entrada aggrega que indique a mesma condição — o mesmo code — que a recusa de uma compilação no mesmo documento, colocada no mesmo intervalo ou em nenhuma chave própria — desenhada onde é desenhada uma entrada que não indica nenhuma chave, ou no início do ficheiro — é omitida de todas as respostas e de todas as publicações para esse documento, e o relatório da compilação fica sozinho. O relatório da compilação é a entrada da recusa na camada aggrega-build; ou, para aggrega/build, aggrega/buildPreview ou aggrega/irGraph recusados com 1004 porque uma dependência não resolve, essa própria resposta — que nada publica — no documento que o seu data.file indica, senão no seu data.lockfile, senão na Release que o pedido indicou, sendo a mais recente dessas respostas para uma Release a que conta. A validação mantém o que encontrou: assim que nenhuma compilação reporte a falha — a execução seguinte publica a camada sem ela, a resposta seguinte de compilação, pré-visualização ou grafo para essa Release é qualquer outra coisa, ou liga-se um cliente a que não foi dada nenhuma resposta 1004 desse tipo — a própria entrada do documento volta a ser reportada, e onde nenhuma compilação foi executada nada é omitido. Uma entrada aggrega colocada numa chave em que não está nenhuma recusa de compilação mantém-se, mesmo quando indica a mesma condição, porque pode ser uma segunda falha desse tipo que a compilação não reportou.
code é um código estável e comparável por máquina para aquilo que a entrada reporta, para que um cliente possa ramificar com base nele sem comparar o texto da mensagem. Uma única chave contém o código, seja quem for que o atribuiu, e source diz-lhe que tipo tem em mãos, porque as camadas dão nomes às coisas a partir de vocabulários diferentes.
- Numa entrada
aggrega— uma constatação sobre os documentos de autoria — o código é a cadeia sob a qual a condição está registada, escrita como o pacote declarante seguido da regra em kebab-case. É o mesmo valor que um consumidor Go lê comCodeOf, cuja forma e superfície comparável são descritas na referência dos sentinelas de erro. - Numa entrada
aggrega-build— um aviso consultivo que uma compilação levantou — o código é o que quer que o local que o levantou tenha atribuído, e esta camada contém avisos de dois vocabulários diferentes porque uma compilação levanta avisos sobre dois tipos diferentes de coisas. Um aviso sobre a forma da topologia implantada contém um código de classe, comounsupported-field, atribuído onde quer que tenha sido levantado, seja um plugin de renderização ou a própria renderização; um código de classe indica uma classe de aviso e não uma condição registada, pelo que não tem linha na referência dos sentinelas, e a referência dos avisos descreve a classeunsupported-fielde a flag que a silencia. Um aviso sobre os documentos de autoria — um nome a uma edição de distância de um declarado, um parâmetro que nada lê — contém a cadeia sob a qual a sua condição está registada, na mesma forma que uma entradaaggregae com uma linha na referência dos sentinelas. Em qualquer dos casos o código indica o que a constatação é e não quem a encontrou, pelo que uma única classe lhe chega sob um único código por muitos que sejam os sítios que a levantam, e ler o código em vez da camada é o que lhe diz qual dos dois tem em mãos. A recusa em que uma compilação parou durante a renderização é a única entrada aqui que não é um aviso, e contém da mesma forma a cadeia sob a qual a sua condição está registada. - Numa entrada
aggrega-lint— uma constatação sobre convenções de publicação — o código é a identidade da constatação: a identidade da regra que a produziu ou, para uma constatação que não indica nenhuma regra — que um linter seu pode reportar sob um código próprio — esse código. É o identificador queaggrega lintimprime na linha da constatação, depois do código curto quando existe, e o valor queaggrega lint --output jsoncontém para essa mesma constatação, comoruleId, ou comocodepara uma constatação que não indica nenhuma regra. Uma constatação mantém uma única identidade entre as superfícies, pelo que um cliente que agrupa ou suprime uma regra no editor agrupa e suprime a mesma regra no terminal. Cada regra do conjunto de regras do linter de publicação que Aggrega declara está registada como condição sob essa identidade, pelo que está listada na tabela de todas as condições sob o código curto queaggrega lintimprime no início da linha da mesma constatação e queaggrega lint --output jsoncontém nela comoshortCode. Uma regra de um linter seu que Aggrega não declara não indica nenhuma condição registada, e o mesmo acontece com uma constatação que não indica nenhuma regra, mesmo quando o seu próprio código soletra a identidade de uma regra que Aggrega declara — pelo que nenhuma das duas está aí listada. As regras são descritas na referência deaggrega lint.
Qualquer que seja a camada, a chave responde a uma pergunta — o que é isto, em termos que uma máquina consegue comparar — pelo que uma extensão de editor que realça, agrupa ou suprime uma classe de constatações baseia-se no código e continua a funcionar quando a redação de uma mensagem muda.
Repare em que objeto contém qual: isto é uma cadeia numa entrada de diagnóstico, distinta do code numérico num envelope de erro JSON-RPC descrito em Códigos de erro abaixo. Uma resposta contém um ou outro, nunca ambos no mesmo sítio.
A chave é omitida quando nada do que produziu a entrada atribuiu um código, e todos os tipos têm esse caso. Um buffer que nenhum analisador YAML consegue ler reporta o próprio texto do analisador e nenhum código, porque nenhuma condição própria de Aggrega está por trás dele; uma fase que reporta uma falha sem indicar uma condição também não tem nenhuma para reportar; e um aviso cujo autor não atribuiu código chega sem nenhum. Por isso, trate code como opcional, tal como end_line e end_column, e ramifique com base nele apenas quando estiver presente. Um código é o que um diagnóstico reporta e nunca o que seleciona um: nenhum pedido aceita um código, e escrever um no seu próprio código dá-lhe uma cadeia e não uma forma de comparar.
O identificador que um programa compara e o que uma pessoa cita
Uma condição tem dois identificadores, e destinam-se a dois leitores diferentes. code é o de cima: qualificado e com hífenes, para que um programa que ramifica com base nele se leia como aquilo que significa. shortCode é a letra E e quatro algarismos — E0164 — e é o que uma pessoa consegue ler em voz alta, escrever numa caixa de pesquisa ou colar num relatório de problema. Ambos indicam a mesma condição e nenhum é abreviatura do outro.
Qual usar decorre de quem está a ler. Compare com code na sua extensão; coloque shortCode diante do autor. Uma extensão que mostrasse apenas code deixaria o leitor com um identificador destinado a um programa, e uma que comparasse com shortCode estaria a comparar com um número que não diz nada sobre a condição. É por essa divisão que ambos viajam em vez de um só.
codeDescription é onde a condição está publicada, contido como { "href": … }, que é a própria estrutura do protocolo para uma referência a abrir para saber mais sobre um diagnóstico. Um editor compatível com o protocolo transforma-a numa funcionalidade «saber mais» sem que lhe ensinem nada sobre Aggrega, e nenhum cliente precisa de uma cópia das explicações. O endereço resolve para a lista publicada de todas as condições, onde a entrada de um shortCode indica a condição e prossegue para o passo a passo da correção de autoria.
A prosa em si não está na entrada, e isso é deliberado. Um diagnóstico é emitido em cada edição, pelo que uma explicação que viajasse em cada um voltaria a publicar os mesmos parágrafos a cada tecla premida a um leitor que normalmente já os leu. Um cliente que queira o texto pede-o uma vez, com aggrega/explainError abaixo; um cliente que consiga seguir uma ligação não precisa de nenhum dos dois.
Ambas as chaves estão presentes exatamente quando a entrada indica uma condição registada, e ausentes em conjunto caso contrário. O que as decide é o que está por trás da entrada e não a camada que a publicou, por isso leia as chaves e não a camada:
- Uma entrada que indica uma condição registada contém as três.
shortCoderesolve, e a referência resolve para a lista em que resolve. - Uma entrada cujo código indica uma classe contém apenas
code. A classe de um aviso de renderização, e a identidade de uma constatação de convenções de um linter seu — uma regra que Aggrega não declara, ou o código que contém uma constatação que não indica nenhuma regra — são identificadores reais com base nos quais pode agrupar e suprimir, e nenhum deles é uma condição registada — pelo que não há número a citar nem nada no endereço que os descreva. Uma referência enviada mesmo assim seria uma ligação que abre uma página que não trata do problema do leitor, e é por isso que nenhuma é enviada. Esta é a forma habitual na camadaaggrega-build, embora um aviso de compilação que indique uma condição registada contenha as três como qualquer outro. Na camadaaggrega-linta forma habitual é o conjunto completo: uma regra do conjunto de regras do linter de publicação que Aggrega declara é uma condição registada, pelo que a sua constatação contém o mesmoshortCodequeaggrega lintimprime no início da linha da constatação, e a referência ao lado. - Uma entrada que não indica nada não contém nenhum identificador.
Assim, os três casos distinguem-se apenas pelas chaves: nenhum code significa nada a indicar, um code sem shortCode ao lado significa um identificador que não resolve mais além, e o conjunto completo significa um identificador com um sítio onde ler sobre ele. Trate as duas chaves novas como opcionais, tal como code, e ofereça ao leitor algo para abrir apenas quando codeDescription tiver chegado.
Expandir um código que um diagnóstico continha
aggrega/explainError transforma qualquer um dos identificadores de uma condição naquilo que o compilador declara sobre ela e nas entradas publicadas que ensinam a correção de autoria. É a mesma expansão que aggrega explain efetua num terminal e que a ferramenta explain-error efetua para um assistente, e as três respondem a partir de um único sítio, pelo que um código expandido aqui e o mesmo código expandido ali são uma única resposta e não três que por acaso concordam.
code é obrigatório e aceita qualquer um dos identificadores — o shortCode que um diagnóstico continha, ou o code ao lado — porque um cliente que tenha um deles não tem forma de obter o outro sem perguntar. Um valor vazio é recusado indicando o que enviar.
A resposta contém sempre shortCode, code e message: os dois identificadores da condição e a frase com que abre todo o diagnóstico que a indica. Estes são declarados dentro do binário, pelo que chegam sem rede e sem cache, o que permite responder a um espaço de trabalho que não contém documentação. reference é o mesmo endereço que o codeDescription de um diagnóstico contém, para um cliente que prefira enviar o leitor para a documentação em vez de apresentar prosa.
entries contém o passo a passo publicado, cada entrada como o heading que a abre e o body por baixo, pela ordem em que a própria documentação os associa à condição. É omitido quando o passo a passo não pôde ser acrescentado, e note diz então porquê: a página publicada ainda não documenta nenhuma entrada para esta condição, ou este espaço de trabalho não consegue ler a documentação — a máquina não tem nenhuma cópia, ou apenas uma que a verificação de assinaturas do espaço de trabalho recusa. Em qualquer dos casos a condição acima mantém-se — a resposta não é uma falha, e um cliente mostra o que chegou e a nota ao lado. entries e note nunca chegam ambos.
Um código que nada resolve é recusado em vez de respondido com uma condição cujos campos estão todos vazios, e cada recusa diz qual é o caso: um código sob o qual nenhuma condição está registada, um número que indicou uma condição no passado e nunca indicará outra, ou um código que este binário não declara quando a lista publicada não pôde ser lida de todo — o último deixa ambas as reparações em aberto, uma vez que uma lista publicada para uma versão diferente pode indicar uma condição que este binário não declara.
A documentação é lida do pacote em cache para o espaço de trabalho que o pedido indica, adquirido na primeira utilização quando está ausente, que é a única coisa para a qual este pedido acede a um registo — consulte Aceder a um registo e escrever. Nada é escrito no espaço de trabalho. Nenhuma validação o desencadeia: uma expansão acontece porque um pedido a solicitou, pelo que nunca se acede a um registo enquanto um documento está a ser validado ou inspecionado.
Convenções de publicação, a pedido e em cada edição
O daemon responde a duas perguntas diferentes sobre uma entidade de catálogo, e são as perguntas a que aggrega validate e aggrega lint respondem no terminal: se a implantação está correta e se a entidade é publicável segundo as convenções do catálogo. Uma validação responde sempre à primeira. Só responde à segunda quando a pede.
aggrega/lint pede-a diretamente. Envie entity para uma entidade de catálogo, release para todas as entidades que o fecho de dependências dessa Release alcança, ou nenhum para verificar todas as entidades sob os diretórios de catálogo configurados — os três âmbitos que o comando tem. Enviar entity e release em conjunto indica dois sujeitos diferentes e é recusado. A resposta contém checked, o número de documentos de entidade que a execução abrangeu, e files, as constatações agrupadas pelo documento a que cada uma diz respeito e ordenadas por caminho, sendo as entradas de cada ficheiro na forma de diagnóstico descrita acima. halted diz se o próprio veredicto da execução recusa a publicação.
Não enviar nenhum verifica todo o catálogo da forma como aggrega lint o faz sem argumento. Um espaço de trabalho cuja configuração não dá a nenhuma Release diretórios de catálogo próprios é verificado uma vez, sobre os seus próprios diretórios, e a resposta é a descrita acima. Um espaço de trabalho que indica Releases em workspace.releases é verificado uma vez por cada Release que contém, sobre os diretórios que essa Release lê, e nunca sobre todos em conjunto — pelo que variantes de catálogo mantidas lado a lado, uma por Release, são cada uma verificada nos termos da Release que as lê. A resposta contém então também passes, uma entrada por passagem: releases, as Releases para as quais foi executada, cada uma relativa à raiz do espaço de trabalho, partilhando uma entrada as Releases que leem os mesmos diretórios; catalogDirs, os diretórios que leu, escritos como files escreve um caminho, e vazio para uma Release que não lê nenhum, o que é reportado em vez de fazer falhar as outras; e as contagens e files próprios dessa passagem, que são o que diz para que Release foi encontrada uma constatação. checked, as contagens e files à volta delas abrangem todas as passagens em conjunto, pelo que um cliente que não lê passes continua a ler toda a execução. Uma execução em que nenhuma passagem tem um diretório para ler é recusada em vez de ser respondida como um catálogo limpo.
Defina prePublish juntamente com entity para comparar essa entidade com a sua versão publicada anteriormente e classificar o aumento de versão proposto em relação a ela. Esse é o único modo aqui que acede a um registo, e é executado porque o pedido o indicou: o que admite uma operação que acede ao exterior é que alguém a tenha pedido. Só tem significado com entity, pelo que prePublish sem entidade é recusado.
aggrega/lint não publica nada na sessão. Responde sobre o sujeito que lhe foi dado, e escrever as suas constatações na lista de problemas do editor substituiria o que uma validação publicou para ficheiros que o pedido nunca abrangeu. Nada é escrito no disco em nenhum modo.
serve.lint_on_validate executa as mesmas regras em cada validação, e está desligado a menos que o ligue. Ligue-o em .aggrega-config.yaml, no espaço de trabalho sobre cujas entidades quer o conselho:
serve: lint_on_validate: trueNão existe nenhuma flag para isso, porque a pergunta a que responde é sobre o conteúdo do próprio espaço de trabalho, e quem tem essa pergunta é quem está a escrever o espaço de trabalho e não quem lançou o daemon. Com ele ligado, uma validação de uma entidade de catálogo publica também as constatações de convenções sob a origem aggrega-lint; com ele desligado — a predefinição — uma validação reporta apenas as camadas de correção e nenhuma constatação de convenções lhe chega. Uma sessão de editor não diz nada sobre se uma entidade é publicável até pedir essa camada.
Três coisas verificam-se nessa camada, diga a chave o que disser. Só é executado o modo que lê conteúdo local, pelo que nenhum registo é consultado, nada é obtido e nada é escrito; a comparação de pré-publicação é alcançada enviando aggrega/lint com prePublish, nunca por uma validação, porque uma verificação executada em cada edição é exatamente onde não se pode aceder a um registo. As regras são avaliadas sobre o buffer que o pedido trouxe e não sobre o ficheiro no disco, pelo que um nome que corrija deixa de ser reportado antes de guardar. E as constatações são consultivas — um documento que as recebe continua a validar, e a sua Release continua a resolver e a renderizar — pelo que acrescenta uma camada e nunca uma recusa.
A chave controla essa camada e nada mais. aggrega/lint responde ao que lhe for perguntado com qualquer dos valores, porque quem o envia pediu a verificação pelo nome.
Só são verificados os tipos que são publicados num catálogo, porque é disso que tratam as convenções. Os documentos que não são conteúdo de catálogo — entre eles um Aggregate e uma Release — são ignorados, tal como o YAML que não é de todo um documento Aggrega. É isso que mantém uma sessão silenciosa quanto aos documentos em que um autor passa a maior parte do tempo.
Como é escrito um caminho reportado
Quando uma resposta indica um documento que o daemon localizou por si, uma regra decide como esse caminho é escrito: relativo à raiz do espaço de trabalho quando o documento está dentro dela, e o caminho absoluto quando não está. Isso abrange o file numa identidade de entidade, o file numa definição de entidade e o file pelo qual cada grupo numa resposta de lint é indexado. Ambas as formas são caminhos que pode abrir — a primeira em relação à raiz que indicou, a segunda tal como está — e nenhuma fica alguma vez vazia por causa do sítio onde o documento está.
A segunda metade da regra é aquilo de que um diretório de catálogo configurado precisa. Um espaço de trabalho pode apontar para diretórios de catálogo em qualquer sítio da máquina, e um documento num deles é tão real como um documento sob a raiz. O caminho absoluto é o que lhe dá nome, e é a mesma forma que aggrega lint e um diagnóstico de paragem imprimem para esse ficheiro num terminal — pelo que um ficheiro tem um único nome qualquer que seja a superfície a que perguntou. O que não lhe será dado é um caminho que sobe acima da raiz, que indicaria ficheiros diferentes consoante o sítio a partir do qual fosse lido.
A forma que recebeu é legível a partir do valor: tudo o que a sua plataforma lê como caminho absoluto é a segunda forma, e tudo o resto é relativo à raiz do espaço de trabalho. Não precisa de o testar para abrir o ficheiro — juntar um relativo à raiz e abrir um absoluto tal como está funcionam ambos — mas um cliente que agrupe por documento do espaço de trabalho consegue distinguir os dois sem perguntar.
O que esta regra não abrange. Um caminho que envia é regido pelo contrato do próprio pedido, indicado com o pedido acima e normalmente mais rigoroso: um destino é recusado a menos que seja relativo à raiz do espaço de trabalho e resolva dentro dela, incluindo as suas ligações simbólicas. A notificação aggrega/publishDiagnostics contém o seu file em forma absoluta em todos os casos, dentro e fora da raiz, porque esse valor é o identificador que compara com os seus próprios documentos abertos e não uma coordenada no espaço de trabalho — o seu editor resolve-o como caminho do sistema de ficheiros. aggrega/releaseCandidates e aggrega/activeRelease indicam cada Release e cada lockfile pelo seu caminho absoluto, como dizem as suas próprias entradas acima. E aggrega/irGraph contém o grafo compilado tal como o compilador o registou — retendo apenas os valores que um autor declarou sensíveis — pelo que qualquer caminho registado nele é o que o compilador registou, na forma que o próprio contrato do grafo fixa, e não um que este protocolo compôs para si.
Que formas aceita um parâmetro que envia
O que um caminho indica — e não o método que o transporta — decide que formas esse parâmetro aceita. A entrada própria de cada pedido acima indica o contrato dos parâmetros que recebe; o que se segue é o contraste entre eles, e porque é um contraste e não uma inconsistência que tenha de memorizar por método.
Um parâmetro que indica um documento que já tem pode ser escrito de qualquer uma de três formas: relativo à raiz do espaço de trabalho, absoluto, ou como o endereço file:// que um cliente de servidor de linguagem envia para um documento aberto. É o file ou o uri de aggrega/validate, aggrega/diagnostics, aggrega/invalidate, aggrega/hover, aggrega/completion, aggrega/resolve, aggrega/findReferences, aggrega/findImplementations, aggrega/insertionPoint e aggrega/connectionAtPosition. As três indicam um único documento e são respondidas da mesma forma, porque cada uma é reduzida a uma única forma canónica no limite do pedido antes de algo a ler — pelo que um documento que validou pelo seu caminho é encontrado pelo seu endereço, e vice-versa, e a forma que envia não muda nada na resposta. Um endereço é lido como o caminho que indica, com os escapes de percentagem descodificados, quando a sua autoridade está vazia ou é localhost; um que indique outra máquina é lido como a partilha de rede dessa máquina num sistema que abre um documento aí dessa forma, e não indica nada que o daemon consiga abrir em qualquer outro sítio. Um endereço que contenha também uma query, um fragmento, credenciais ou uma porta também não indica nada que o daemon consiga abrir. Um valor que não comece por file://, quaisquer que sejam as maiúsculas e minúsculas, nunca é lido como endereço, e a recusa de ficheiro não validado indica o valor que enviou, qualquer que fosse a forma. Destes, aggrega/insertionPoint e aggrega/connectionAtPosition são os dois que leem o documento do disco quando não tem nenhuma cópia dele, e respondem apenas para um documento dentro do espaço de trabalho: um fora da raiz — tal como escrito, ou através de uma ligação simbólica que conduz para fora dela, para o ficheiro ou para um diretório pelo caminho — é recusado qualquer que seja a das três formas que o indica, e um documento dentro da raiz é respondido nas três. Os outros oito não leem nada do disco no caminho que indicam — aggrega/validate obtém os bytes do documento de content, e os restantes respondem a partir do que foi validado — pelo que respondem para um documento onde quer que o tenha, dentro do espaço de trabalho ou não, e nenhuma ligação simbólica que indiquem é seguida para ler um ficheiro. Um parâmetro que indica um documento que selecionou fora do espaço de trabalho é o mesmo caso pela mesma razão: o source de aggrega/import é lido onde realmente está, como diz a sua própria entrada. Ambos são exceções à fronteira do espaço de trabalho por classe — um documento que o cliente tem aberto e um ficheiro que uma pessoa escolheu — e A fronteira do espaço de trabalho explica porque cada uma o é.
Um parâmetro pelo qual o daemon tem de localizar um documento dentro do espaço de trabalho aceita um caminho relativo ao espaço de trabalho e mais nada. release é o que convém conhecer — em aggrega/irGraph, e com o mesmo contrato onde quer que apareça — e um valor absoluto é recusado com o erro invalid-params, que indica o contrato e depois a falha específica. Os pedidos que escrevem dentro do espaço de trabalho sujeitam os seus destinos a esse mesmo contrato, como diz a entrada de cada um. Cada um desses caminhos é então avaliado pelo sítio para onde conduz, por uma única regra quer o pedido o leia quer o escreva — a definição de dentro que A fronteira do espaço de trabalho indica — e um caminho que conduz para fora é recusado com o erro próprio desse pedido, citando o valor tal como o enviou, sem nada lido ou escrito: uma ligação simbólica para um ficheiro fora e uma ligação simbólica para um diretório pelo caminho igualmente, e um caminho ainda não criado por baixo de um diretório ligado que conduz para fora, que é recusado por causa da ligação em vez de ser escrito, ou procurado fora e reportado como em falta. Isso abrange todos os caminhos que um pedido indica para o daemon ler — release onde quer que apareça, o entity de aggrega/lint e os entity, plugin, file e from dos pedidos de publicação — pelo que um pedido não consegue ler através de uma ligação simbólica um ficheiro que as próprias listagens do espaço de trabalho deixam de fora, e todos os destinos: os diretórios em que uma geração, uma importação e uma compilação escrevem, a entidade ao lado da qual aggrega/pin escreve o seu lock, o ficheiro de entidade e o módulo que aggrega/pluginSync lê e reescreve, e o documento que aggrega/editDocument edita. Uma release que indique uma Release que a configuração do seu espaço de trabalho indica é a única exceção, como diz a entrada de aggrega/irGraph.
Os dois diferem porque as falhas diferem. Um parâmetro que indica um documento que já tem deixa apenas uma pergunta — que documento — pelo que reduzir a sua forma à canónica não perde nada, e aceitar cada uma também não lhe custa nada. Um parâmetro que seleciona um documento a partir do espaço de trabalho não está nessa posição: nas bibliotecas de caminhos que um cliente provavelmente usa, juntar um valor absoluto a uma raiz dá esse valor absoluto em vez de um erro. Assim, um valor reparado silenciosamente levaria o daemon a ler — e a reportar constatações sobre — um caminho que o espaço de trabalho nunca conteve, e seria informado sobre um ficheiro que não existe. Recusar é a resposta, em vez de reparar, porque um daemon que reparasse um tal valor deixaria todos os clientes que o enviassem convencidos de que o contrato era opcional.
Como é endereçada uma entidade
Todas as entidades que uma resposta indica são endereçadas da mesma forma: kind, name e file. Junte por essas três com aggrega/catalogIndex para tudo o que queira apresentar: é a superfície que contém o conjunto descritivo completo de uma entidade — apiVersion, description e labels — pelo que uma resposta que só precisa de indicar uma entidade reporta as três chaves de endereçamento e deixa a descrição para um único sítio. Uma consulta por nome como aggrega/entityDefinition repete os poucos campos descritivos de que trata a sua própria resposta; o índice continua a ser a superfície com que juntar quando quer o conjunto.
Quando uma resposta pode indicar entidades de mais de um sítio, cada identidade contém origin ao lado dessas três chaves. aggrega/catalogIndex e aggrega/attachCandidates fazem-no ambos, porque as suas entidades vêm dos documentos do espaço de trabalho e dos diretórios de catálogo configurados. Uma resposta que recorre a um único sítio reporta apenas as três chaves e nenhum origin, uma vez que uma chave com um único valor possível não lhe diz nada — todas as entidades que tal resposta indica são documentos do espaço de trabalho, e o seu file é um caminho relativo ao espaço de trabalho que pode abrir. Por isso, leia origin onde estiver presente em vez de o exigir em todo o lado; as três chaves são aquilo por que junta em qualquer caso.
origin pertence a uma resposta que lista entidades, em que distinguir as populações é o problema do leitor. Uma resposta por nome como aggrega/entityDefinition não contém nenhum: indica a única entidade para a qual o nome resolveu, pelo que não há populações a separar. O seu próprio ponto acima diz quando o seu file está vazio; não leia esse vazio através dos valores de origin abaixo, que descrevem uma listagem.
origin diz de onde o daemon leu a entidade, e é o que torna file legível.
workspace— um documento Aggrega sob a raiz do espaço de trabalho.fileé o seu caminho relativo a essa raiz, que é um caminho que o seu cliente pode abrir.catalog— uma entidade resolvida a partir dos diretórios de catálogo configurados.fileestá vazio nesta listagem, e onameé o endereço completo. Está vazio porque a listagem reporta o que a consulta ao catálogo enumerou, que é uma identidade e não um documento, pelo que a entrada não tem caminho a reportar — não é um caminho que tenha sido retido por causa do sítio onde está. Peça aaggrega/entityDefinitiono mesmo nome quando quiser o documento: esse pedido resolve a entidade e reporta o seufilesegundo a regra acima, pelo que um diretório de catálogo fora da raiz do espaço de trabalho é aí indicado pelo seu caminho absoluto.nameé a coordenada que um Aggregate, uma Recipe e a consulta ao catálogo usam de qualquer forma.
Leia os dois em conjunto em vez de testar apenas file. Um file vazio por si só não lhe diria se a entidade não tem caminho no espaço de trabalho ou se simplesmente não foi reportado; origin responde a isso diretamente.
Quando uma Feature é alcançável das duas formas — a própria raiz do espaço de trabalho é um dos diretórios de catálogo configurados, o que é uma disposição comum — é reportada uma vez, como documento do espaço de trabalho, porque é essa a cópia cujo ficheiro pode abrir.
O que uma resposta de candidatos a anexo lhe diz
aggrega/attachCandidates responde a uma única pergunta — que Features admite este conjunto de etiquetas — e oferece três formas de dizer a que conjunto de etiquetas se refere. Envie exatamente uma coordenada; enviar duas, ou nenhuma, é recusado em vez de ordenado.
{node} endereça um documento do espaço de trabalho pelo seu metadata.name e não precisa de mais nada. A correspondência é avaliada com as etiquetas que esse documento declara em metadata.labels, e a resposta reporta labelSource: "declared".
{graphNode, release} endereça um nó de um grafo compilado. graphNode é o id sob o qual o grafo indexa o nó — o mesmo id que lê de aggrega/irGraph, incluindo a forma qualificada que tem um nó contribuído por um subagregado. release é um caminho relativo à raiz do espaço de trabalho, que indica a Release cujo grafo construir, o mesmo valor que aggrega/irGraph aceita. A correspondência é avaliada com as etiquetas finalizadas do nó, e a resposta reporta labelSource: "resolved".
{labels} contém o próprio conjunto de etiquetas e não endereça nada. É a forma subjacente às outras duas: a correspondência é uma função de um conjunto de etiquetas e das Features disponíveis, pelo que um cliente que já tem um conjunto de etiquetas não tem nada a indicar nem nada por que esperar. Envie um objeto JSON de pares de etiquetas; a resposta reporta labelSource: "supplied" e um node vazio, porque este pedido não endereçou nenhum. Um objeto vazio é uma coordenada — pergunta por um nó sem etiquetas — enquanto omitir completamente a chave, ou enviar null, não endereça nada e é recusado.
As duas coordenadas de nome são separadas porque os seus espaços de identificadores se sobrepõem. Um id de nó do grafo e o metadata.name de um documento podem ser a mesma cadeia e indicar coisas diferentes, pelo que um parâmetro que transportasse ambos seria ambíguo, e um daemon que adivinhasse a que espaço se refere responderia por vezes com confiança sobre o sujeito errado. Dizer que pergunta está a fazer é o que elimina a ambiguidade.
labelSource diz-lhe até onde vai a resposta, e os três valores não são intercambiáveis. declared é uma correspondência sobre o que um documento diz de si próprio, que é o que uma leitura do código-fonte consegue ver. resolved é uma correspondência sobre as etiquetas com que o nó efetivamente fica, que é aquilo com que uma compilação avalia a aplicabilidade — pelo que uma resposta resolved é uma afirmação sobre o que uma compilação decidiria, e uma resposta declared não é. supplied diz que o daemon não leu nenhuma etiqueta e comparou o que enviou; a força dessa resposta depende inteiramente da origem do seu conjunto de etiquetas.
É por isso que um cliente que tem um grafo deve enviar {labels} em vez de um nome. As etiquetas finalizadas de um nó são as etiquetas do tipo de componente para o qual resolve, não de um documento que por acaso partilha o seu id, e um anexo label-transform pode depois acrescentá-las, alterá-las ou removê-las — pelo que as etiquetas que decidem a aplicabilidade de um nó não têm de ser as que algum documento declara. Um cliente que desenha um grafo já tem esse conjunto de aggrega/irGraph; devolvê-lo chega à mesma resposta que a coordenada {graphNode, release} dá, sem reconstruir o grafo para a obter. Devolva um conjunto que o próprio daemon reportou — o de um nó de aggrega/irGraph, o de uma entidade de aggrega/catalogIndex — e a sua ideia das etiquetas de um nó não pode divergir da do daemon, porque o conjunto nunca saiu da sua própria resposta. Monte um por si e está a fazer uma pergunta hipotética, que é respondida honestamente e não é uma afirmação sobre nenhum nó que o espaço de trabalho contenha.
Os candidatos vêm do espaço de trabalho e do catálogo. Um espaço de trabalho que mantém as suas Features num catálogo em vez de na sua própria árvore não tem nenhuma Feature local, e os seus candidatos são inteiramente origin: "catalog". Para um nó do grafo, ambos são lidos nos termos da Release desse nó: as Features do catálogo são as que declaram os diretórios de catálogo que a configuração do espaço de trabalho dá a essa Release, e os documentos próprios do espaço de trabalho são oferecidos excluindo os que estão sob um diretório de catálogo que só outras Releases leem. Um espaço de trabalho que mantém uma variante de uma Feature por Release oferece assim ao grafo de cada Release a sua própria variante e nunca a de outra, enquanto uma Feature escrita ao lado dos catálogos, sob nenhum diretório de catálogo, é oferecida para cada Release. {node} e {labels} não indicam nenhuma Release, pelo que recorrem a todos os documentos do espaço de trabalho e aos catalog_dirs do próprio espaço de trabalho. Uma Feature que não declara nenhuma aplicabilidade é candidata para todos os nós — uma declaração ausente não estabelece nenhum requisito — enquanto uma cuja declaração não pode ser lida não é candidata para nenhum, porque tratar um seletor ilegível como satisfeito permitiria que um erro de escrita alargasse o que oferece.
Um nome que não resolve é um erro, não uma lista vazia. Essas duas respostas significam coisas diferentes: um array candidates vazio diz que este nó não tem nada que se possa anexar a ele, e reportar assim um nome mal escrito apresentaria um erro de escrita como uma resposta definitiva. A recusa indica o espaço em que procurou, para que saiba se deve procurar um documento do espaço de trabalho ou um nó do grafo. {labels} não tem esse risco — não há nome que possa ter sido mal escrito — pelo que um conjunto de etiquetas que nada admite regressa como resposta bem-sucedida com um array vazio, e um pedido que o daemon não consegue ler continua a ser recusado antes de qualquer correspondência ser executada.
A coordenada de nó do grafo precisa de um lockfile; as outras duas não. Construir um grafo significa resolver o que a Release alcança, pelo que esse caminho recusa com o erro de lockfile ausente quando nenhum foi gerado, indicando o comando a executar — a mesma pré-condição que aggrega/irGraph tem, pela mesma razão. Endereçar um documento do espaço de trabalho não constrói nenhum grafo, e fornecer um conjunto de etiquetas não constrói nada, pelo que ambos respondem num espaço de trabalho que ninguém preparou ainda.
Reporta e nunca cria. O método não altera nada, não escreve nada e não cria nenhum anexo. Compor e aplicar qualquer edição cabe ao editor, que é onde estão o buffer e o histórico de anulação.
O que resolve depende da coordenada, e as três não são iguais. {node} não resolve nada e não acede a nenhum registo nem à rede — os candidatos vêm do espaço de trabalho e dos diretórios de catálogo, ambos já no disco. {labels} resolve ainda menos: não consulta nada, porque não há nada a consultar. {graphNode, release} constrói o grafo da Release, pelo que resolve o fecho de dependências dessa Release da mesma forma que aggrega/irGraph: primeiro a partir dos diretórios de catálogo locais e da cache de artefactos, e a partir do registo configurado para uma entidade que nenhum deles contenha. As três respondem offline para um espaço de trabalho cujas entidades são todas locais; só a coordenada de nó do grafo pode ir procurar mais longe.
Perguntar sobre uma conexão
Uma conexão que um componente estabelece pode ter anexos próprios, que preenchem os slots que o seu socket declara no Component consumidor — uma credencial que o componente apresenta ao que quer que a conexão alcance, por exemplo. Envie connection ao lado de {graphNode, release} para perguntar o que pode ir aí: socket é o socket de dependência através do qual a conexão é ligada e alias o nome que tem dentro desse socket, ambos exatamente como o autor os escreveu. Uma conexão só existe num grafo compilado, pelo que connection ao lado de node ou labels é recusado, tal como uma conexão que não indique socket ou alias, ou uma que o nó não estabelece.
A resposta é a resposta de nó do grafo mais os slots da conexão. candidates mantém o seu significado — as Features que se podem anexar ao próprio nó — e slots é acrescentado, uma entrada por cada slot que o socket declara, pela ordem em que o Component os declara:
slot— o nome sob o qual um anexo que o preenche é escrito nasfeaturesda conexão.selector,required,inject,sensitiveedescription— o slot exatamente como o Component o declara no socket, vazio ou false quando não declara nada.selectoré a restrição pela qual os candidatos foram reduzidos, para que possa explicar um candidato, ou a sua ausência, apenas a partir da resposta.candidates— as Features que podem preencher este slot nesta conexão. Uma compilação sujeita um tal anexo a duas regras, e ambas são aplicadas: a aplicabilidade declarada da Feature em relação às etiquetas finalizadas do nó, a que todos os anexos do nó estão sujeitos, e oselectordo slot em relação às próprias etiquetas da Feature. Assim, os candidatos de um slot estão sempre entre os do nó, reduzidos pelo seletor. Uma Feature em relação a cujas etiquetas o seletor não pode ser avaliado não é oferecida, porque uma compilação recusa-a em vez de a admitir.
Quando nenhum slot pode ser preenchido, slots é uma lista vazia e noSlotReason diz porquê. Leia o motivo em vez de tomar uma lista vazia por «nenhuma Feature correspondeu» — isso seria uma resposta diferente, e o motivo é o que as distingue:
feature-created-connection— uma Feature estabeleceu a conexão, a partir do seu próprio bloco de dependências. Um anexo só é escrito numa conexão que um componente ou a Release estabelece, pelo que nada vai aqui, declare o socket o que declarar.ad-hoc-socket— o socket é um que o Component não declara. O autor deu-lhe nome, o que é legal, e um socket não declarado não declara nenhum slot.no-slot-declared— o Component declara o socket sem nenhum slot.
noSlotReason está ausente sempre que existe um slot, e slots e noSlotReason estão ambos ausentes de uma resposta a um pedido que não indicou nenhuma conexão — pelo que um pedido que não indica nenhuma conexão é respondido sem nenhum dos dois campos.
document é aceite e aqui não muda nada. Os slots são os do socket e os candidatos os das Features, os mesmos qualquer que seja o documento em que um anexo é escrito; onde vai é a resposta de aggrega/attachmentContainer. Um valor diferente de aggregate ou release continua a ser recusado, porque um valor aceite e ignorado parece ao seu remetente um que foi respeitado.
O que uma resposta de candidatos a conexão lhe diz
aggrega/connectionCandidates responde a duas perguntas ao mesmo tempo, e só uma delas tem uma resposta completa. Ler a resposta como uma única lista filtrada erra a outra.
Cada socket reportado contém targets — os Components locais do espaço de trabalho cujas etiquetas declaradas satisfazem a restrição de etiquetas que esse socket declara sobre o que o pode satisfazer — mais o selector a partir do qual esses alvos foram calculados, a flag required que o socket declara, e declaration. targets é sempre um array, vazio em vez de ausente, pelo que um socket que nada satisfaz continua a ser reportado como um socket que a entidade declara.
A metade dos alvos é completa. O conjunto é decidido avaliando a restrição declarada do socket em relação às etiquetas declaradas de um candidato, a mesma avaliação que uma compilação efetua, pelo que o que oferece é o que a mesma restrição admite durante uma compilação. Um socket que não declara nenhuma restrição deixa os seus alvos sem restrição e reporta cada Component — é esse o significado da linguagem de restrições para um seletor vazio, não um erro.
A metade dos sockets é aberta, e declaration mais adHocSocketsAccepted são a forma de o saber. O autor de um Aggregate é dono da sua topologia e pode ligar um socket que a entidade de catálogo do componente nunca declarou, pelo que os sockets que uma entidade declara são um conjunto inicial útil e não o conjunto de nomes de socket legais. Apresente-os como sugestões, não como as únicas opções — um seletor que oferecesse apenas sockets declarados diria ao autor que a sua liberdade é mais estreita do que é.
declarationédeclaredquando a entidade endereçada lista o socket no seuusesSchema, ead-hocquando não lista. São os mesmos dois valores que uma aresta tem no grafo IR, pelo que um único vocabulário responde a «de onde veio este socket» onde quer que encontre a pergunta.adHocSocketsAcceptedreporta se a superfície da entidade endereçada aceita um socket que a sua própria declaração não lista. Não é sempre verdadeiro: a superfície de dependências própria de um Component aceita um, e a superfície de anexos de uma Feature não, porque um anexo participa na topologia que a Feature anexada declara em vez de escrever a sua própria. Um socket ad hoc numa superfície que não aceita nenhum é reportado sem alvos, porque nenhuma conexão através dele compilaria.
Indicar um socket no pedido limita a resposta a esse socket, e é a única forma de perguntar por um socket que a entidade não declara — um socket não declarado não aparece em nenhuma declaração a enumerar. Omita-o para obter todos os sockets que a entidade declara, pela ordem em que estão escritos.
O que reporta é uma correspondência sobre etiquetas declaradas. Uma compilação avalia a restrição de um socket em relação às etiquetas finalizadas do nó na outra ponta da aresta, e essas são as etiquetas do tipo de componente para o qual esse nó resolve, depois de qualquer anexo label-transform ter tido a sua palavra — não necessariamente as etiquetas do documento que indicou. Assim, uma resposta positiva aqui não é uma promessa sobre o que uma compilação decidirá — o mesmo limite que aggrega/attachCandidates tem sob a sua origem de etiquetas declared.
Reporta e nunca cria. O método não resolve nada, não acede a nenhum registo nem à rede, e não escreve nada: não cria nenhuma aresta nem propõe nenhum texto. Compor e aplicar a edição cabe ao editor, que é onde estão o buffer e o histórico de anulação.
Para as identidades de entidade em targets — kind, name e file — junte com aggrega/catalogIndex como descrito em Como é endereçada uma entidade. Os campos descritivos são aí reportados e deliberadamente não são repetidos aqui, pelo que esta resposta não contém uma segunda cópia deles que possa ficar dessincronizada. Os alvos são Components do espaço de trabalho, pelo que todos têm um file que pode abrir e nenhum contém um origin: esta resposta recorre a um único sítio, e a junção é feita pelas três chaves.
O que uma resposta de contentor de anexo lhe diz
aggrega/attachmentContainer situa-se entre os pedidos de candidatos acima e o ponto de inserção abaixo. Esses dizem o que se pode anexar a um nó; este diz em que contentor pertence um anexo para ele, e em que documento; o seguinte diz onde, nos bytes desse documento, vai o texto.
Peça o contentor em vez de o compor. O id de um nó e o caminho de subsistemas que o envolve são ambos escritos com pontos entre as suas partes, e um ponto é um carácter legal num nome que um autor escreve — pelo que, de fora do documento, não há forma de distinguir um ponto estrutural de um dentro de um nome. Um cliente que montasse o caminho por si produziria algo que parece correto e endereça uma chave que ninguém escreveu, e a edição que se seguisse criaria essa chave em vez de ser recusada. Foi o compilador que compôs ambos os caminhos, por isso é o compilador que os desmonta.
O id de um nó não tem nenhum vestígio do subsistema que o envolve. Um componente escrito dentro de subsystems.billing.subsystems.payments é indexado no grafo como ledger, exatamente como um componente de nível superior o seria, pelo que não há nada no id a partir do qual um cliente possa trabalhar, por mais cuidadosamente que o divida.
A resposta tem três campos.
noderepete o nó a que a resposta se refere, para que um cliente com vários pedidos pendentes associe cada resposta à sua pergunta sem manter uma ordem própria.fileé o documento em que o nó foi escrito, relativo ao espaço de trabalho. Faz parte da resposta em vez de ser algo que já sabe: um nó que um módulo importado contribuiu foi escrito no próprio documento desse módulo sob o nome que o módulo lhe deu, pelo que tanto o ficheiro como o último segmento do contentor diferem de tudo o que o pedido indicou.containeré o caminho estrutural a partir da raiz desse documento, como lista de segmentos —["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Cada nível de um subsistema envolvente fica de novo sob a chavesubsystems, que é como o documento o escreve. Um componente que o autor escreveu no nível superior indica["spec", "components", "checkout", "features"], porque o âmbito em que tal componente é compilado não é um que algum ficheiro contenha.
É uma lista de segmentos e nunca uma cadeia unida, e é esse o objetivo da forma. Um caminho unido teria de ser dividido de novo por quem o recebesse, o que reintroduz a ambiguidade acima uma chamada depois. Passe a lista a aggrega/insertionPoint como o seu container sem alterações.
Lê a estrutura e nunca o significado. A resposta é derivada do documento em que o nó foi escrito, do âmbito em que está e do nome que o autor escreveu. Nada é inferido do nome de um componente, do tipo que tem ou do que diz qualquer etiqueta.
Reporta e nunca escreve. O método não altera nada e não escreve nada em nenhum documento. Não cria nenhum anexo, não compõe nenhum texto e não aplica nenhuma edição; não decide o que se pode anexar, que é aggrega/attachCandidates.
Um pedido que indique um nó que o grafo não contém é recusado em vez de respondido. Os ids dos nós são as próprias chaves do grafo — leia-os do grafo que aggrega/irGraph devolve — e um nó que um módulo importado contribuiu tem um id qualificado. Um nó para o qual o grafo não regista nenhum documento também é recusado: onde pertence um anexo é um facto sobre um documento, pelo que um nó sem documento não tem resposta, e não uma resposta vazia.
Requer um lockfile, pela mesma razão que aggrega/irGraph: indicar o contentor significa construir o grafo da Release, e um grafo construído a partir de bytes que nada garante seria reportado exatamente como um que foi verificado.
Um anexo numa conexão
Envie connection ao lado de {graphNode, release} — o seu socket, o seu alias e o seu document — e a resposta indica o contentor features na própria entrada dessa conexão em vez do do nó. document é aqui obrigatório, porque qualquer dos documentos pode conter um anexo numa conexão que o Aggregate estabeleceu: o programador escreve um na entrada da conexão no Aggregate, o operador na entrada por aresta da Release para ela.
aggregateindica a entrada da conexão no documento em que o nó foi escrito —["spec", "components", "gateway", "uses", "models", "gpt", "features"]para um componente de nível superior, com cada subsistema envolvente escrito nível a nível como acima. Uma conexão que a Release estabeleceu não tem entrada no Aggregate, pelo que é aí recusada.releaseindica a entrada por aresta sob a própria entrada da Release para o nó —["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"]— quer a Release já escreva essa entrada por aresta quer não. Quando não escreve,aggrega/insertionPointreporta as chaves ainda por escrever emmissingContainerKeys.fileé então o documento da Release. Uma Release que não escreve nenhuma entrada para o nó é recusada: onde o nó é colocado cabe ao operador escrever, e a resposta não o decide.
Uma conexão que uma Feature estabeleceu é recusada em qualquer dos documentos, pela razão que feature-created-connection dá acima. O nó, o socket e o alias são comparados exatamente como escritos, e uma conexão que o nó não estabelece é recusada em vez de respondida com um caminho. Todas as outras propriedades acima se mantêm inalteradas: a resposta é uma lista de segmentos, lê a estrutura e nunca o significado, e não escreve nada.
O que uma resposta de conexão numa posição lhe diz
aggrega/connectionAtPosition é o passo anterior aos dois pedidos de conexão acima, para um cliente que tem um sítio num documento em vez de um nó num grafo — um cursor na entrada de uma conexão, por exemplo. Responde que conexão está escrita aí, nas coordenadas que esses pedidos aceitam, e fica por aí.
A resposta é uma de duas metades, nunca ambas.
graphNodeeconnection— o nó cujo componente estabelece a conexão, pelo id sob o qual o grafo compilado o indexa, e a conexão pelo seusocketealias, comdocumenta indicar o documento em que a posição foi lida:aggregatepara o Aggregate ou um módulo que este importa,releasepara a Release. PassegraphNode, a mesmareleaseeconnectionaaggrega/attachCandidatespara obter os slots que o socket da conexão declara, e aaggrega/attachmentContainerpara saber onde vai um anexo nela; o contentor que indica fica dentro da própria entrada em que a posição caiu.noConnectionReason— porque não é reportada nenhuma conexão. O conjunto é fechado:no-connection-entry— a posição não está em nenhuma entrada em que se escreva um anexo. Uma conexão escrita como lista de alvos (db: [store]) e uma que o próprio bloco de dependências de uma Feature estabelece não têm tal entrada, pelo que uma posição em qualquer delas também dá esta resposta.feature-created-connection— a posição está na entrada da Release para uma conexão que uma Feature estabeleceu, que não tem anexo pela razão que a resposta sobre slots dá acima. Uma Release escreve tal entrada quando o bloco de dependências de uma Feature estabelece uma conexão através de um socket que o Component consumidor também declara; a entrada compila quer não configure nada, quer defina oinfrapor aresta da conexão.unknown-connection— a posição está numa entrada que a Release escreve para uma conexão que o grafo compilado não contém. Uma Release que compila pode conter uma — por exemplo uma entrada sob um alias que nada estabelece e que não configura nada (semtarget, seminfra, semfeatures), ou uma entrada para um componente que um interruptoractive:desligou, cujas conexões saem da compilação com ele.
Que entradas contam. No Aggregate, todas as conexões que um componente estabelece, na sua entrada sob o alias da conexão no documento em que o componente foi escrito — para um componente que um módulo importado contribui, o próprio documento desse módulo. Na Release, todas as entradas por aresta que escreve, quer a entrada estabeleça a sua conexão quer configure uma que o Aggregate estabeleceu. Onde cada entrada fica é o que o grafo compilado regista, pelo que se uma chave é uma conexão nunca é deduzido do seu nome. Um componente que um interruptor active: desligou não está no grafo compilado, pelo que as suas próprias entradas no Aggregate respondem no-connection-entry, enquanto a entrada da Release para uma das suas conexões responde unknown-connection.
Uma posição em qualquer sítio dentro de uma entrada está dentro dela. A entrada vai da sua chave de alias até à última linha indentada por baixo dela, pelo que uma posição no alias, no seu target ou dentro das suas features é respondida para essa conexão, e a entrada mais interior ganha quando as entradas se aninham. Uma posição na própria chave de um socket, acima dos aliases escritos sob ela, não está dentro de nenhum deles — quer o socket contenha um alias quer vários — e o mesmo acontece com uma posição na indentação antes de uma chave de alias.
Que documento é qual decorre da Release. O próprio ficheiro da Release é lido para as entradas que escreve; qualquer outro ficheiro é lido para as entradas em que o grafo regista componentes como escritos. Um documento do qual o grafo da Release não lê nada responde no-connection-entry em todas as posições.
Reporta e nunca escreve, e lê o documento da forma como aggrega/insertionPoint o faz: primeiro a partir da cópia da sessão e, caso contrário, do disco, dentro do espaço de trabalho, com as mesmas recusas para um documento que esteja fora dele, que seja ilegível ou que não seja YAML bem formado. Requer um lockfile, pela razão que aggrega/attachmentContainer o requer, e constrói o grafo sem nada renderizado.
O que uma resposta de ponto de inserção lhe diz
aggrega/insertionPoint é a contrapartida dos dois pedidos de candidatos acima. Esses dizem o que se pode anexar ou ligar; este diz onde pertence o texto correspondente num documento concreto. Responde e fica por aí.
Indica o contentor; o daemon localiza-o. container é um caminho estrutural a partir da raiz do documento — ["spec", "components", "web", "features"] — e é a sua afirmação de onde pertence uma entrada deste tipo num documento deste tipo. O daemon não deriva esse caminho do nome de uma entidade, do tipo que tem ou do que parece significar. Lê os bytes que o autor escreveu e reporta que segmentos do caminho este documento já tem, as colunas em que as suas entradas estão e a última linha que o seu bloco mais interior alcança. Assim, saber que chave fica com quem chama, e saber onde vão as entradas dessa chave neste ficheiro vem daqui.
Para um anexo de Feature num nó de um grafo compilado, quem chama não tem de conhecer essa chave por si: peça a aggrega/attachmentContainer o documento e o contentor, e passe ambos aqui sem alterações.
A resposta é uma posição de largura zero mais o que tem de escrever à volta dela. file é o documento, relativo ao espaço de trabalho. container repete o caminho sobre o qual perguntou, para que um cliente com vários pedidos pendentes associe cada resposta à sua pergunta sem manter uma ordem própria. position insere em vez de substituir: nada do que já está no documento é sobrescrito ou deslocado.
precededByLineBreak— comece o texto que escreve com uma quebra de linha. A posição fica no fim da linha que a nova entrada segue, que está dentro do intervalo quer o ficheiro termine numa nova linha quer não, e não perturba nenhum byte já escrito. Só é false para um documento que não contém nada a seguir ao qual ficar, em que escreve a partir do início do ficheiro.missingContainerKeys— os segmentos do caminho do contentor que este documento ainda não contém, do mais exterior para o mais interior. Cada um tem de ser escrito como chave própria antes de a entrada poder ir dentro do mais interior. Fica vazio quando todo o caminho já existe.entryIndent— a coluna em que começa a primeira linha da própria entrada, contada em espaços a partir do início da linha.indentStep— quanto mais cada nível de aninhamento é indentado.indentStepMeasured— se esse passo foi medido a partir do aninhamento do próprio documento. Quando é false, o documento não exibe nenhum aninhamento a medir e o passo é um valor de recurso, pelo que um cliente que prefira impor o seu sabe que é livre de o fazer.entryShape—mappingousequence, lido do que o contentor já contém, eunknownquando o contentor ainda não existe ou não contém nada.unknownnão é uma falha: o documento não disse que forma têm as suas entradas, pelo que essa escolha é sua.
Aplicá-la. Escreva uma quebra de linha quando precededByLineBreak estiver definido. Depois uma linha por cada entrada de missingContainerKeys, da mais exterior para a mais interior, cada uma sendo a chave seguida de dois pontos — a primeira indentada em entryIndent menos indentStep vezes o número de chaves em falta, e cada uma das seguintes indentStep mais à frente. Depois a própria entrada, indentada em entryIndent. Quando missingContainerKeys está vazio, a entrada é a única linha que escreve.
Leia missingContainerKeys mesmo quando espera que o contentor exista. Uma posição aplicada sem as chaves que têm de a preceder produz um documento que deixa de ser analisável, que é a única falha que esta resposta não pode dar a entender como ausente.
position conta a partir de zero, ao contrário da de um diagnóstico. Tanto line como character têm base 0, de acordo com os valores de posição no formato LSP que este protocolo reutiliza, enquanto o line e o column numa entrada de diagnóstico têm base 1, como descrito em O que contém uma entrada de diagnóstico. Um cliente que alimente uma superfície a partir da outra converte entre elas.
positionEncoding indica as unidades em que character é medido, e é a codificação negociada no handshake. É reportado na resposta em vez de ficar implícito porque uma posição cujas unidades quem chama tem de adivinhar é uma posição que não consegue aplicar: deslocamentos medidos de uma forma e aplicados num buffer medido de outra corrompem o documento no primeiro carácter fora do ASCII.
Um pedido que não endereça um sítio onde uma entrada possa ir é recusado em vez de respondido. Cada um destes casos é um estado do pedido e não do espaço de trabalho, pelo que regressa com o código invalid-params padrão e uma nova tentativa não muda nada até file ou container mudarem.
- O documento não foi indicado, não está dentro do espaço de trabalho, não pôde ser lido ou não é YAML bem formado — um documento sem estrutura não tem posição a reportar.
- O caminho do contentor não indica nada: não tem segmentos, ou um dos seus segmentos está vazio.
- O caminho passa por um valor que o documento contém como escalar. Nada pode ser acrescentado dentro de um escalar, e substituí-lo seria uma reescrita e não uma inserção.
- O caminho alcança uma coleção que o autor escreveu em estilo de fluxo. Acrescentar uma entrada a uma reescreve bytes que o autor já escreveu em vez de adicionar uma linha, o que é uma edição e não uma posição.
- O caminho endereça uma sequência de bloco com algo que não é um dos seus índices. As entradas de uma sequência são endereçadas por posição, pelo que um nome não alcança nada nela e nenhuma entrada pode ser criada para ter esse nome.
Lê o buffer que o editor tem, e não apenas o ficheiro no disco. A cache de análise do daemon é consultada primeiro, pelo que uma posição é reportada em relação ao conteúdo não guardado quando existe, e em relação ao próprio ficheiro quando a cache não tem nada para ele.
Reporta e nunca escreve. O método não altera nada, não resolve nada, não acede a nenhum registo nem à rede, e não escreve nada em nenhum documento. Não compõe o texto de uma entrada nem a aplica. Compor e aplicar a edição cabe ao editor, que é onde estão o buffer e o histórico de anulação.
O que uma resposta de edição de documento lhe diz
aggrega/editDocument é a outra metade do par acima: esses dizem onde pertence uma entrada e deixam-no compô-la e aplicá-la; este compõe e aplica uma, e escreve. Ambos continuam disponíveis, porque um cliente com um buffer não guardado e um cliente que edita o que está no disco querem metades diferentes — um editor com o seu próprio histórico de anulação coloca o texto por si, enquanto um cliente que prefere que o ficheiro seja editado a ser informado de onde editar envia este.
Uma chamada aplica uma edição, e o conjunto de edições é fechado. edit indica qual: add-component acrescenta uma instância de componente sob um contentor de componentes, attach-feature anexa uma Feature a um nó, wire-edge liga uma conexão dentro de um dos sockets de dependência de um nó, e set-value define um valor num nó. Não há nenhuma edição que elimine, substitua um bloco que já escreveu, reordene algo ou escreva literalmente bytes que fornece — pelo que isto não é um escritor de ficheiros com um nome mais restrito, e um valor fora dos quatro é recusado em vez de interpretado. A recusa lista o que pode indicar.
Indica o nó como um caminho estrutural, exatamente como os dois pedidos acima o aceitam. node é o caminho de navegação a partir da raiz do documento — ["spec", "components", "web"] — e o contentor em que a entrada vai decorre de edit. Para add-component o caminho indica o próprio contentor de componentes, porque a entrada a acrescentar é o nó. name é a chave sob a qual a entrada é escrita: o nome da instância, o nome do anexo, o alias da conexão ou a chave do valor. value é o que essa entrada contém, e o que significa decorre de edit — a entidade que a entrada pede, o nó para o qual uma conexão aponta, ou o escalar para o qual um valor é definido. socket é lido para wire-edge e ignorado nos restantes casos.
Um caminho em vez de um nome, pela razão pela qual o pedido de localização aceita um: um nome teria de ser procurado, e um nome que aparecesse em dois níveis deixaria o compilador a decidir a qual se referia. Assim, um cliente que sabe que nó está a editar di-lo, e um cliente que não sabe sabe que tem uma pergunta a responder antes de editar o que quer que seja.
Todos os bytes que a edição não toca sobrevivem. O documento é analisado apenas para localizar o contentor e a linha em que o seu bloco termina; a entrada é renderizada e inserida ao nível da linha. Comentários, linhas em branco, estilo de aspas, escalares dobrados e literais, expressões de modelo e a forma da nova linha final passam todos sem alterações, e o passo de aninhamento é medido a partir da própria indentação do documento em vez de imposto — pelo que uma entrada fica no estilo em que já está a escrever. O mesmo pedido sobre o mesmo documento produz os mesmos bytes, pelo que um cliente pode comparar duas execuções e uma revisão lê uma edição como um único diff.
O resultado tem de ser um documento que poderia ter escrito, e é disso que a escrita depende. O documento composto é validado com o esquema do seu próprio tipo e só chega ao disco se passar. Um pedido que produziria algo que o esquema de autoria recusa regressa como E0275 — the edit was refused because the resulting document would not be valid, and nothing was written (a edição foi recusada porque o documento resultante não seria válido, e nada foi escrito) — com a propriedade que o esquema não admitiria e onde. O ficheiro fica byte a byte como estava, pelo que uma edição recusada é indistinguível de uma nunca tentada e pode tentar de novo um pedido corrigido sobre o documento com que começou. É também por isso que nenhuma regra é aqui repetida: pedir que um documento de Release contenha um valor do programador é recusado pelo mesmo esquema que recusaria o documento escrito à mão.
O que é semanticamente admissível não é decidido aqui. Se um socket de dependência é um que o produtor declara, ou se a aplicabilidade de uma Feature está satisfeita, pertence à resolução que uma compilação efetua, cada uma com o seu próprio relatório. Assim, pode indicar uma conexão de que este pedido nunca ouviu falar, e um Aggregate pode escrever um socket que a sua entidade de catálogo não pré-declara; o que pode ser consumido através de um socket continua a caber ao produtor declarar. Execute aggrega/validate indicando uma Release, ou peça o grafo, quando for essa a pergunta.
A resposta indica o que ficou e o que chegou ao disco, e são perguntas diferentes. content contém o documento que a edição produziu em ambos os modos de entrega. written indica o ficheiro que chegou ao disco, e está vazio com dryRun. container é o caminho estrutural do contentor em que a entrada ficou, para que possa localizar o que acabou de acrescentar sem voltar a derivar essa regra. createdContainers indica os segmentos que esta edição escreveu porque o documento não os continha, do mais exterior para o mais interior — vazio no caso habitual em que todo o caminho já existia, e lê-lo é como distingue uma entrada acrescentada dentro de um bloco existente de uma que criou o seu próprio bloco. file e edit repetem o que enviou, para que um cliente com vários pedidos pendentes associe cada resposta à sua pergunta. written, container e createdContainers são sempre arrays, vazios em vez de ausentes.
Com dryRun nada é criado. written fica vazio, content contém o documento que uma escrita teria produzido, e o ficheiro não é tocado — pelo que um editor pode colocar o resultado diante do autor para guardar, alterar ou descartar. A predefinição é a escrita, porque o produto da operação é um documento editado e uma superfície que produz um deve entregá-lo: um pedido que não diz nada sobre a entrega edita o ficheiro.
Tudo o que uma escrita faz, uma execução de ensaio faz. O documento composto é validado com o esquema do seu próprio tipo em qualquer dos casos, pelo que uma edição que uma escrita recusaria é recusada também com dryRun, indicando a mesma propriedade — o que significa que o erro que obtém de uma execução de ensaio é o erro que a escrita lhe teria dado.
Uma entrada que já existe, com o que pediu, é uma operação nula — o documento regressa inalterado e nada é escrito. Uma entrada com esse nome que contenha outra coisa é recusada em vez de substituída, porque substituir o que um autor escreveu não é uma das quatro edições.
Depois de uma escrita o daemon volta a ler o documento. O que tinha para esse ficheiro é descartado e a sua vista ao nível do espaço de trabalho é reposta, pelo que o pedido seguinte de validação, hover, completação ou grafo é respondido a partir dos bytes que a edição produziu e não da versão que substituiu. A própria edição lê o ficheiro no disco e não o buffer que tem — ao contrário do pedido de localização acima, que consulta primeiro o conteúdo não guardado. Isso é deliberado: escrever a partir de um buffer não guardado poria na página conteúdo que o autor não guardou, a pretexto de aplicar uma entrada. Guarde o buffer e depois edite.
Um pedido que não endereça um sítio onde uma entrada possa ir é recusado em vez de respondido, com o código invalid-params padrão, e uma nova tentativa não muda nada até o pedido mudar. O documento não foi indicado, não está dentro do espaço de trabalho, não pôde ser lido, não é YAML bem formado ou não declara nenhum tipo com cujo esquema o resultado possa ser verificado; edit não foi indicado ou não é um dos quatro; node não indica nada, ou um dos seus segmentos está vazio; não foi dado nenhum name; wire-edge não indicou nenhum socket; set-value recebeu um mapeamento ou uma sequência onde pertence um escalar; o caminho do nó alcança um escalar ou uma sequência, ou uma coleção escrita em estilo de fluxo, onde acrescentar uma linha reescreveria bytes já na página; ou o caminho do nó não alcança nada no documento.
Não resolve nenhuma dependência, não acede a nenhum registo e não toca na rede em nenhum dos modos de entrega.
O que a resposta de configuração efetiva abrange
aggrega/effectiveConfiguration responde a duas perguntas: que configuração se aplica nesta sessão, e que camada decidiu cada definição. É a mesma resposta que aggrega config show --origin imprime, calculada uma vez e reportada em ambas as superfícies, pelo que as duas não podem discordar sobre a origem de uma definição.
Um source tem uma de quatro formas. O caminho absoluto de um ficheiro de configuração — incluindo o ficheiro global que um daemon iniciado como aggrega --config <file> serve lê, indicado como o caminho que lhe foi dado; uma variável de ambiente após um prefixo env:, como env:AGGREGA_SIGNING_REQUIRED; uma flag global escrita na linha de comandos que iniciou o daemon, indicada como a flag, como --offline para um daemon iniciado como aggrega --offline serve; ou (built-in defaults) para uma definição que nenhuma camada define. As três primeiras aparecem literalmente em layers. As predefinições não, porque as predefinições não são uma camada que contribuiu — são o que se aplica onde nenhuma camada se pronunciou.
Uma definição é atribuída à camada de maior precedência que a define, qualquer que seja o valor que essa camada escreve. Um ficheiro de configuração que escreve a predefinição incorporada, ou que repete um valor que um ficheiro abaixo dele já define, é o ficheiro indicado: é ele que mantém o valor no lugar. Um ficheiro define uma definição ao conter a sua chave, incluindo o companheiro _append de uma lista, e uma variável de ambiente ao ser exportada com um valor não vazio. O ficheiro de configuração que o seu pipeline detém nunca é indicado para uma chave que ignora. aggrega config show --origin reporta segundo a mesma regra.
Todas as definições que o esquema de configuração declara são contabilizadas, embora não cada uma com uma linha própria. O companheiro aditivo _append de uma lista é reportado na linha da lista a que acrescenta, pelo que uma camada que contribui apenas através do companheiro é indicada na linha dessa lista e o companheiro não tem linha. Uma definição dentro das entradas de uma lista — a política de confiança de um registo, os parâmetros de entrada de um anexo de plugin — é abrangida pela linha dessa lista.
Mais dois limites, cada um dos quais torna uma resposta mais grosseira do que parece.
- Uma definição de lista ou de mapa é atribuída como um todo, à camada de maior precedência que a define. A atribuição por entrada não é registada, pelo que uma lista montada a partir de duas camadas reporta apenas a de maior precedência, e uma entrada contribuída por uma camada inferior não é distinguível de uma que a camada superior escreveu.
- O requisito de assinatura é atribuído à primeira camada que o ativou, não à última que o mencionou. Essa definição compõe-se de forma que qualquer camada que a ative ganha e nenhuma camada posterior a pode desativar, pelo que a primeira camada a ativá-la é a que tornou o valor efetivo no que é. Uma camada que escreve
required: falsenão ativa nada, pelo que, quando todas as camadas que a mencionam escrevemfalse, a definição reporta(built-in defaults).
Cada valor reportado é a resolução feita quando esse espaço de trabalho foi indicado pela primeira vez. Editar um ficheiro de configuração não altera aqui um valor; reiniciar o daemon altera. Isso é deliberado — os valores são a configuração sob a qual todos os outros pedidos sobre esse espaço de trabalho são respondidos, o que os torna comparáveis com a raiz e a camada de configuração que o handshake reportou para ele. Um cliente que mostre a configuração ao lado de um ficheiro que o utilizador está a editar deve dizer qual dos dois está a mostrar.
A atribuição de camadas é calculada quando pergunta, com os ficheiros tal como estão. Assim, um ficheiro de configuração editado depois pode mudar um source enquanto o valor ao lado permanece como foi resolvido. As duas metades respondem a perguntas diferentes — o que está em vigor e que camada o decidiu — e só a primeira é fixa. Reinicie o daemon para as voltar a sincronizar.
Reporta e nunca escreve. O método não altera nenhuma configuração, não cria nenhum ficheiro e não resolve nada a partir de um registo ou da rede.
O conteúdo de ficheiro de uma única camada não é servido aqui. A linha de comandos pode imprimir literalmente os bytes de uma camada, com comentários e formatação preservados; este método reporta a resolução e não os bytes. Um cliente que queira o texto de uma camada tem o caminho em layers e pode abri-lo.
O que uma escrita de configuração deixa para trás
aggrega/configInit e aggrega/configCapture produzem ambos um documento de configuração, e ambos o escrevem. A resposta indica o ficheiro; abri-lo é o seu ato seguinte, não um substituto da escrita. Nenhum deles lhe entrega conteúdo para colocar por si a menos que o peça diretamente, porque uma capacidade cujo produto é um documento que nunca foi escrito é uma capacidade diferente com o mesmo nome.
Os dois diferem no seu alcance, e cada resposta diz qual. Leia-o antes de mostrar o resultado.
- Semear escreve, por predefinição, a configuração partilhada por todos os espaços de trabalho da máquina. Um registo e as identidades em que confia nele são normalmente os mesmos onde quer que trabalhe, por isso é aí que a entrada vai, a menos que o pedido envie
workspace: true.scopecontém oconfigFileque foi escrito emachineWide, que diz se é o partilhado — derivado do ficheiro para o qual a escrita resolveu e não do que o pedido pediu, pelo que uma resposta não pode descrever uma alteração a toda a máquina como local. - Congelar nunca vai além do espaço de trabalho. Não recebe destino de escrita nem substituição: todo o seu objetivo é tornar um projeto autossuficiente, pelo que escreve sempre o
.aggrega-config.yamldesse projeto. É por isso que a sua resposta contémconfigFileeworkspaceRoote não reivindica nenhum âmbito — não há alcance a declarar.
Semear recusa em vez de sobrescrever. Um ficheiro de configuração que já existe é deixado intacto e a recusa indica-o, porque semear destina-se a uma configuração que ainda não existe, enquanto a escrita partilhada para a qual delega funde por conceção. Envie force para escrever mesmo assim; a entrada do registo é fundida no que já existe e as restantes definições são preservadas. Um pedido recusado não altera absolutamente nada.
trust diz o que a política anunciada pelo registo fez, como resultados separados e não como prosa. pinned significa que o registo anunciou uma política e esta foi adotada, com identities a contá-las. notAdvertised significa que o registo foi consultado e não anunciou nenhuma, o que não é uma falha — a sementeira prossegue, e reason diz o que o endpoint fez. Um registo que não pôde ser alcançado também é reportado assim, uma vez que nenhuma política voltou e a sementeira prossegue da mesma forma, e contém unreachable ao lado quando a própria falha mostra que o registo nunca foi alcançado: o seu nome não resolveu, uma conexão a ele foi recusada ou não pôde ser aberta, ou não foi possível estabelecer uma conexão segura a ele. Um registo que respondeu — com um not-found, ou com um estado de erro — nunca contém unreachable, por isso leia essa chave em vez das palavras de reason para distinguir um registo que não publica nenhuma política de um que nunca foi consultado. baseline significa que a base incorporada do hub oficial foi fixada porque nenhuma política anunciada foi adotada, com reason a dizer porquê; a entrada contém uma política, pelo que não há nada a fixar à mão. As duas chaves respondem a perguntas diferentes, pelo que um hub que foi consultado e não anunciou nada contém ambas, e um hub num espaço de trabalho offline — nunca consultado — contém apenas baseline, com reason a dizer que o espaço de trabalho está offline. Qualquer outro registo que não anuncia nada contém apenas notAdvertised, é semeado sem política, e o conselho que se segue é fixar identidades à mão; offline é recusado em vez de respondido. skipped significa que não foi tentada nenhuma obtenção. Um cliente que tratasse tudo o que não seja pinned como erro reportaria uma configuração funcional como avariada.
Com dryRun nada é criado. written é false, content contém o documento que uma escrita teria produzido, e o ficheiro a que esse conteúdo se destina é scope.configFile. Nenhum diretório é criado e nenhum ficheiro é tocado, pelo que um editor pode colocar o texto diante do autor e deixá-lo guardar, alterar ou descartar.
Uma execução de ensaio difere de uma escrita exatamente num aspeto — não escreve — pelo que todas as recusas que uma escrita efetua também as efetua. A recusa por ficheiro existente é a que aqui importa: dryRun sobre um ficheiro de configuração que já existe é recusado, indicando o ficheiro, exatamente como uma escrita. É isso que torna a resposta utilizável como predicado — se a execução de ensaio recusa, a escrita teria recusado, pela mesma razão e com a mesma mensagem. Envie force juntamente com dryRun para obter como resposta a fusão que uma escrita com sobrescrita produziria, continuando a não escrever nada. O registo é contactado para obter a sua política de confiança anunciada em ambos os modos de entrega, porque a política nesse conteúdo é a política que uma escrita teria fixado.
O que um congelamento reporta é o que escreveu, não uma descrição disso. sockets lista cada socket de plugin que foi congelado com os anexos aí congelados; catalogDirs contém os diretórios de catálogo. Ambos são sempre arrays, vazios em vez de ausentes.
socketefieldnão são a mesma cadeia, e a diferença não é cosmética.socketindica o socket a que os anexos estão associados;fieldé a chave sob a qual foram escritos no ficheiro. Diferem apenas para o socket de fornecedor, que é escrito sob uma chave no plural — por isso usefieldquando indicar ao leitor uma linha do documento esocketquando der nome ao próprio socket.- Cada anexo contém
uri,capability,functionerole, presentes apenas quando o anexo os tem. Dão nome ao anexo em vez de o reproduzirem por completo: os parâmetros de entrada opcionais de um anexo no momento da anexação são congelados literalmente no ficheiro e não são repetidos na resposta. O ficheiro é a cópia de referência. captured: falseé um sucesso. Um projeto em cuja configuração uma compilação não participa não tem nada crítico para a compilação a congelar, pelo que o ficheiro fica como está e ambas as listas regressam vazias. Tratar isso como erro reporta um espaço de trabalho saudável como avariado.
A predefinição congela apenas o que determina os bytes do resultado — as associações de fornecedor e os anexos de governação que transformam etiquetas. As barreiras de veredicto de governação e de linter e o socket de importação ficam de fora, porque se destinam a variar entre ambientes e congelá-los levaria as barreiras de um ambiente para todos os checkouts. allPlugins: true alarga o conjunto a todos os sockets de plugin. A pertença é por anexo, não por socket, pelo que um socket de governação com um anexo de transformação de etiquetas e um anexo de veredicto contribui apenas com o primeiro na predefinição.
Cada valor é congelado no seu valor efetivo — o que resolve com a configuração da máquina e a do próprio projeto fundidas — pelo que uma associação que hoje vem apenas da configuração da máquina é escrita no projeto e viaja com ele. As definições de ferramentas a nível da máquina, entre elas a política de confiança de um registo, não são críticas para a compilação e ficam onde estão. Congelar duas vezes sobre uma configuração inalterada reescreve os mesmos bytes, pelo que um cliente o pode oferecer livremente: uma segunda chamada deixa o documento que um leitor tem exatamente como estava.
O que uma alteração de plugin lhe diz
Os quatro pedidos de plugin escrevem todos por predefinição, e dividem-se pelo que escrevem: dois alteram um ficheiro de configuração e dois produzem documentos no espaço de trabalho. Dois deles — a adição e a geração — aceitam dryRun, que faz tudo o resto que o pedido faz e não escreve nada. Leia o relato da própria resposta sobre onde a alteração ficou em vez de o inferir a partir do pedido — para um deles, o pedido não dizer nada sobre o âmbito significa o alcance mais amplo.
Uma adição e uma remoção contêm ambas scope, e este é derivado do ficheiro para o qual a escrita resolveu. configFile é esse ficheiro, machineWide diz se é aquele através do qual todos os espaços de trabalho desta máquina resolvem, e workspaceRoot indica o espaço de trabalho sobre o qual esta sessão foi aberta, pelo que uma resposta com âmbito de espaço de trabalho diz qual era. machineWide é lido do ficheiro resolvido e não do que o pedido pediu, o que impede uma resposta de descrever uma alteração a toda a máquina como local.
🔴 Uma adição do tipo cli que não indique nem global nem workspace regista o comando em toda a máquina. Uma extensão de comando é uma ferramenta de toda a máquina, pelo que sem substituição é escrita no ficheiro de configuração global através do qual todos os espaços de trabalho desta máquina resolvem — e o comando que regista passa a ser um comando aggrega de nível superior para todos os projetos dessa máquina, incluindo projetos que ninguém nesta sessão indicou. Uma adição provider, governance, linter ou importer é ao contrário: essas moldam a compilação de um projeto, pelo que sem substituição vão para o .aggrega-config.yaml desse projeto. Uma remoção segue a mesma regra para os mesmos tipos. Envie workspace: true para manter uma extensão de comando local, ou global: true para enviar qualquer um dos outros para o ficheiro partilhado; enviar ambos é recusado. O scope na resposta é a declaração de referência em qualquer dos casos, e um cliente deve mostrá-lo antes de agir com base no resultado.
Uma adição indica o que ficou, e exatamente um de três campos diz que tipo de coisa era. type repete o tipo para o qual a entrada foi adicionada, e depois: identity contém a identidade de entidade simples fixada por versão para um anexo governance, linter ou importer; uri contém o endereço de artefacto oci:// do plugin, juntamente com a capability que agora serve, para uma associação provider; e reference contém a referência fixada cujos comandos foram registados para uma instalação cli. Assim, quem chama lê que tipo de anexo ficou a partir da resposta em vez de o voltar a derivar do tipo que enviou. Uma remoção repete type e query ao lado do seu scope e mais nada — não há mais nada a reportar sobre uma entrada que desapareceu.
Uma adição contém também written e, com dryRun, content. written é aquilo com base no qual um cliente ramifica: true indica um ficheiro de configuração agora no disco que o cliente pode abrir, e com dryRun é false e content contém em vez disso o documento de configuração que a escrita teria produzido. Os dois nunca têm ambos significado, e o ficheiro a que content se destina é scope.configFile, pelo que nada na resposta contém uma segunda cópia desse caminho — o que aqui importa, porque o ficheiro de um anexo global é aquele através do qual todos os espaços de trabalho desta máquina resolvem.
Um plugin sem versão publicada é recusado em vez de anexado sem fixação. Uma adição resolve a consulta para um plugin e fixa a sua versão publicada mais alta, pelo que a entrada que escreve contém uma versão. Um plugin cujo repositório não publica nenhuma versão conforme é recusado com a indicação do mesmo, e uma versão que uma retração em que este espaço de trabalho confia retirou é ignorada em favor da seguinte abaixo.
Uma versão que a consulta indica é fixada mesmo quando foi retirada, e withdrawn assinala-o. Uma query escrita como <name>:<version> fixa essa versão em vez da mais recente — em todos os tipos exceto provider, que é associado apenas pelo nome e recusa uma versão — e indicar uma versão é a substituição: onde uma retratação em que este espaço de trabalho confia a retirou, é fixada mesmo assim, e a resposta inclui withdrawn: true — o facto que aggrega plugin add indica como uma linha retraction: no terminal. withdrawn está ausente em todas as outras respostas, pelo que a sua presença é todo o sinal — e a sua ausência não afirma que a versão não esteja retirada. Onde os marcadores de retirada de uma versão indicada não puderam ser lidos, withdrawn está ausente e retraction inclui unscreened, indicando porquê, tal como acontece com uma adição que não indica nenhuma versão e encontra a mesma falha; uma adição que não indica nenhuma versão comunica antes em retraction o que a verificação de retirada concluiu sobre a versão que escolheu.
Um alinhamento reporta se alterou algo, e é esse o campo com base no qual agir. changed separa uma escrita de um alinhamento que encontrou os dados já corretos: um ficheiro inalterado foi deixado idêntico byte a byte, pelo que um cliente que tenha esse documento não tem nada a recarregar, e executar o pedido duas vezes não reporta nenhuma alteração na segunda. entity indica o ficheiro, hostFunctions contém o conjunto derivado e commands contém o espelho como valores e não como a linha que um terminal imprime — cada entrada com um name, um description opcional e flags, cada flag com o seu name e os seus shorthand, description, type e default opcionais. A escrita é atómica, pelo que um cliente que leia esse ficheiro enquanto o alinhamento decorre nunca observa um documento parcial.
Uma geração preenche exatamente uma metade da sua resposta, e o próprio dryRun da resposta diz qual. Na predefinição as entidades são escritas e notices contém o que a geração disse sobre as escritas que efetuou. Com dryRun nada é criado nem modificado: documents contém cada entidade gerada como o path a que se destina e o seu content, para que um cliente as possa colocar no seu próprio modelo de documento, onde ficam visíveis antes de serem guardadas e podem ser alteradas ou descartadas. As duas metades nunca são ambas preenchidas, pelo que o modo de entrega executado é legível a partir da resposta e não do que foi pedido.
Onde um pedido de plugin ESCREVE é sempre dentro do espaço de trabalho que esse pedido indicou; o que LÊ é decidido por campo. Um destino absoluto, um que sobe para fora da raiz e um que conduz para fora dela através de uma ligação simbólica são recusados em vez de resolvidos — pelo que uma geração não pode criar entidades numa árvore sobre a qual a sua sessão nunca foi aberta, envie o que enviar. Um caminho que um pedido apenas lê é uma questão separada, respondida campo a campo e não por uma única regra sobre todos: aggrega/pluginGenCatalog lê um módulo e a sua sobreposição de onde quer que os tenha selecionado, porque um módulo que compilou fica no diretório de saída da sua cadeia de ferramentas e recusar lê-lo aí recusaria a operação no seu próprio propósito. aggrega/pluginSync lê os seus dois caminhos dentro do espaço de trabalho, porque esse pedido trata de um ficheiro que o espaço de trabalho já contém. Os pedidos de localização acima aceitam um caminho absoluto por outra razão ainda — um documento que o cliente já tem aberto, indicado pela forma que tiver.
Um pedido a que falte algo de que a operação precisa é recusado indicando o campo a enviar. Uma adição ou uma remoção sem type ou query; uma adição provider sem capability, ou uma governance sem role; uma adição cli sem acceptCapabilities; um alinhamento sem entity ou plugin; uma geração que indique ambos os modos de seleção ou nenhum, ou a que falte overlay ou outputDir. Cada um regressa com o código invalid-params padrão, e uma nova tentativa não muda nada até o pedido mudar. Uma remoção cuja consulta não corresponde a nenhuma entrada também é recusada, indicando o tipo, a consulta e o ficheiro em que procurou — esse é um estado da configuração e não do pedido, pelo que o que há a corrigir pode ser qualquer um deles.
Nada é solicitado interativamente, e a única decisão que teria sido pedida a uma pessoa chega antes como campo. O comando de terminal pergunta a quem estiver a ver se aceita as capacidades declaradas de um plugin de extensão de comando. Ninguém está a ver este fluxo, pelo que acceptCapabilities cabe a quem chama obter e enviar, e um pedido que não o contenha é recusado com a indicação do que enviar em vez de instalar com base num consentimento que ninguém deu. Um daemon que foi iniciado sem os meios para instalar uma extensão de comando recusa logo uma adição cli, em vez de reportar um sucesso que não instalou nada.
Que tipos pode oferecer a um autor
aggrega/getSchema sem kind responde a que tipos pode indicar, e responde em duas larguras porque um cliente precisa de uma diferente para cada tarefa. Leia aquela por que está a perguntar.
kinds é cada token a que o binário responde. entityKinds é o conjunto de que um autor escreve documentos. A lista larga contém a representação intermédia, o lockfile, a configuração do espaço de trabalho e os contratos dos sockets de plugin ao lado dos tipos que escreve — esquemas reais, cada um deles, mas não documentos de que alguém escreva um ficheiro. Assim, a lista larga é aquela a partir da qual configurar a associação de esquemas de um editor, e a estreita é aquela a partir da qual construir um seletor. Um seletor construído a partir da lista larga oferece valores que nenhum esquema de autoria aceita, e o autor só encontra a recusa depois de escolher um.
O conjunto estreito é também mais estreito do que os tipos de entidade, e nenhum esquema lhe diz quais. Um tipo detido pela plataforma cujo conteúdo é escrito dentro do documento de outro tipo não é um documento a oferecer a um autor para começar. Workload é um desses tipos: o conteúdo de workload é escrito no campo workload: de uma Recipe ou de uma FeatureRecipe, quer em linha quer a partir de um ficheiro que esse campo importa, pelo que não há nenhum documento de workload a endereçar por si só — consulte a superfície de autoria de Workload para saber onde vai esse conteúdo. O seu esquema fixa apiVersion e kind exatamente como o esquema de um tipo de autoria o faz, porque é isso que permite validar o conteúdo onde está; os valores fixos identificam o conteúdo e não o tornam endereçável. Por isso não são sinal de que um tipo é um a redigir. entityKinds contém a resposta, e nada nos bytes do esquema a contém.
Cada entrada de entityKinds contém ambas as formas de que um cliente precisa, e nenhuma é derivável da outra. kind é o token em minúsculas com hífenes — envie-o de volta como kind a este método ou a aggrega/scaffoldEntity. documentKind é o valor que o próprio documento contém no seu campo kind: de nível superior. As duas diferem em mais do que maiúsculas e minúsculas para um tipo cujo nome tem mais do que uma palavra: nada do que possa fazer a featurerecipe chega a FeatureRecipe. Tire cada uma da entrada em vez de derivar uma da outra, e não resta nenhum mapeamento para o cliente manter.
Cada entrada diz também que operações aceitam um documento do seu tipo, para que um controlo que ofereça essas operações sobre um documento ofereça apenas as que não o recusam pelo seu tipo. acceptedBy contém três booleanos, cada um presente em todas as entradas, e cada um diz respeito a um documento do tipo indicado por si só — pelo seu caminho, ou pelo seu nome para inspeção — sem mais nada enviado ao lado. singleEntityValidation indica se aggrega validate <path> verifica um documento do tipo, em vez de o recusar e indicar o âmbito de catálogo completo ou de Release que o verifica. publication indica se aggrega/publishEntity que indique apenas o documento o publica: um Plugin é false, porque a sua publicação associa também o executável que um pedido indica em plugin, pelo que um pedido que indique apenas o documento é recusado; um Manifest e uma Release são false porque nenhum desses tipos é publicado. inspectionByName indica se aggrega/entityDefinition resolve um nome para uma entidade do tipo, com o nome enviado tal como é escrito onde uma entidade referencia outra — um Plugin como <pluginType>/<name>, e uma Recipe ou uma FeatureRecipe como <capability>/<name>, ou apenas pelo nome quando só uma capacidade declara esse nome. Um true diz que a operação não recusa o documento por ser desse tipo; pode ainda assim recusar um documento concreto pelo que o documento diz.
Não mantenha nenhuma lista própria. Os tipos que existem são uma propriedade do binário com que está a falar, pelo que uma lista escrita num cliente concorda no dia em que é escrita e deixa de concordar no dia em que um tipo é acrescentado — e o que o autor vê então é o seu tipo a faltar no único controlo que o devia oferecer. Pergunte, e a resposta acompanha o binário.
Ambas as metades chegam juntas, e apenas quando não indica nenhum tipo. Um pedido que indique um tipo responde com o esquema desse tipo e não contém nenhuma das listas, pelo que a pergunta que fez é legível a partir da resposta. Um token a que nenhum esquema corresponde é recusado com todo o conjunto válido na mensagem, com o código invalid-params padrão, pelo que um erro de escrita é um pedido a corrigir e não algo a perguntar a uma pessoa.
Responde num espaço de trabalho que não contém nada. O vocabulário está compilado no binário, pelo que isto não precisa de nenhum documento, lockfile ou catálogo — que é o espaço de trabalho em que está um autor que começa o seu primeiro documento.
O que uma resposta de esqueleto lhe dá
Esta secção trata da criação de rascunhos. A outra forma do método escreve um exemplo executável, e a sua resposta é descrita com o método acima.
aggrega/scaffoldEntity devolve texto. skeleton é YAML para o tipo que indicou: todos os campos que o esquema desse tipo exige, pela ordem em que o esquema os declara. Um campo que o esquema fixa num único valor chega preenchido — apiVersion e kind são os que vai notar — metadata.name contém o name que enviou, e todos os outros valores obrigatórios chegam como marcador de posição com o tipo que o esquema aí declara: uma cadeia vazia, um zero, um false, uma lista vazia, um mapeamento vazio. kind repete o token para o qual o documento foi derivado, para que um cliente com vários pedidos pendentes atribua uma resposta a partir da própria resposta em vez de manter uma correlação própria.
Não escreve nada, e é essa a parte em torno da qual desenhar. O método não cria nenhum ficheiro, não escolhe nenhum caminho e não toca em nenhum diretório. O que recebe é um documento a escrever, não um documento que foi escrito — por isso um editor coloca o texto num novo buffer não guardado que o autor pode ler, editar ou descartar, e o momento em que um novo ficheiro chega ao disco fica onde estão o buffer e o histórico de anulação. Nenhum outro pedido pega neste documento e o coloca algures por si; decidir onde um novo documento vive cabe ao editor.
Não resolve nada, e não precisa de nada do espaço de trabalho. O documento é derivado dos esquemas que o binário contém, pelo que o método não acede a nenhum registo nem à rede, não consulta nenhum catálogo e não lê nenhum ficheiro. Responde da mesma forma em todos os espaços de trabalho, incluindo um diretório vazio sem nenhum documento Aggrega ainda — que é exatamente o espaço de trabalho em que está um autor que começa o seu primeiro documento, e onde a maioria dos outros métodos aqui quereria primeiro um documento ou um lockfile.
O mesmo pedido dá os mesmos bytes onde quer que seja feito. O documento é produzido por um único cálculo partilhado com as outras superfícies que oferecem esta capacidade, pelo que um editor e um assistente a quem se peça o mesmo tipo e o mesmo nome mostram ao autor o mesmo texto inicial.
O esqueleto contém os campos que o seu tipo exige, e não é um documento acabado. Contém os campos obrigatórios e nada mais: um campo opcional que queira é um que acrescenta, e cada marcador de posição é um valor ainda em falta. Preencha os marcadores de posição e depois execute aggrega/validate sobre o buffer. Para uma entidade de catálogo de um tipo que aggrega validate verifica como entidade única, esse método indica cada marcador de posição ainda em falta, cada um na sua chave com o que aceita, pela mesma leitura que o comando aplica ao ficheiro guardado — incluindo um marcador de posição que o esquema admite vazio, sendo o capability e o implements de uma Recipe ou de uma FeatureRecipe redigida os que vai encontrar. Para qualquer outro tipo sujeita o buffer ao esquema do seu tipo, pelo que um marcador de posição que o esquema recusa vazio — uma versão, por exemplo — regressa como constatação desse esquema, e um que o esquema admite vazio não dá nenhuma. Validação em tempo real descreve a entrada como a qual chega cada marcador de posição.
O que uma resposta de importação lhe diz
aggrega/import converte uma origem escrita para outra ferramenta em documentos Aggrega em rascunho, e escreve-os — ao contrário do esqueleto acima, que lhe entrega texto. written indica cada ficheiro que chegou ao disco, relativo a outputDir; files contém cada ficheiro que o pedido escreve com o seu content, quer tenha sido escrito quer não — cada rascunho que o importador produziu e depois o histórico do que a importação escreveu, ou, com sync, o que a sincronização altera. Os dois respondem a perguntas diferentes, por isso leia aquele por que está a perguntar: o que está agora no disco, ou o que foi produzido.
Escolhe para onde vão os rascunhos, ou deixa isso à raiz do espaço de trabalho. outputDir é opcional, tal como aggrega import --output-dir e o output_dir da ferramenta import do assistente: um pedido que não indique nenhum redige sob a raiz do espaço de trabalho — onde aggrega import escreve quando não lhe é dado nenhum destino, onde quer que seja executado — e um pedido que indique um redige aí. Um diretório indicado é um caminho dentro do espaço de trabalho, e um valor relativo resolve em relação à raiz do espaço de trabalho e não a um diretório em que o daemon por acaso esteja. O source que converte é o outro caso e não está confinado desta forma: selecionou esse ficheiro ou diretório, pelo que é lido onde quer que esteja, e lê-lo aí não muda onde os rascunhos ficam. O diretório é criado se não existir. Com dryRun nada é escrito, e cada rascunho continua a indicar o caminho a que se destina, relativo ao outputDir que a resposta indica — o diretório que enviou, ou a raiz do espaço de trabalho.
Um pedido nunca escreve por cima de um Aggregate já existente em outputDir. Um Aggregate é o documento que um autor continua a editar depois de redigido, pelo que um pedido em que um dos rascunhos ficaria num ficheiro que é lido como um Aggregate é recusado, indicando o rascunho e onde está o Aggregate, e absolutamente nada é escrito — também com dryRun, uma vez que uma execução de ensaio recusa o que a escrita recusa. Envie sync para o atualizar em relação à origem, ou indique outro outputDir para redigir ao lado dele. Qualquer outro ficheiro já existente num caminho redigido é sobrescrito, e um ficheiro que uma importação anterior redigiu e que esta não redige é deixado onde está. Todos os pedidos que redigem algo escrevem também .aggrega-import.json em outputDir, o histórico do que a importação escreveu — o target que lhe foi enviado, quando foi enviado um, o instantâneo do catálogo que leu, quando leu um, e cada ficheiro redigido e, num Aggregate ou numa Release redigidos, cada chave a qualquer profundidade, com um digest do texto aí escrito, sendo qualquer outro ficheiro redigido registado por inteiro — e files e written contêm-no depois dos rascunhos. É JSON, pelo que nada do que lê os documentos YAML do espaço de trabalho o lê; sync, tal como aggrega import --sync, lê-o para atualizar os rascunhos em relação à sua origem. Um sync a que não foi enviado nenhum target redige para o destino que o histórico indica, pelo que redige o Manifest que a importação anterior redigiu; um a que foi enviado um target redige para ele, e o histórico passa então a indicá-lo. Um destino registado a que nenhuma Recipe do catálogo se associa é recusado tal como um enviado, dizendo a recusa que o destino é o registado. Como uma Release redigida é registada chave a chave, o ambiente que o seu autor escreve onde a importação deixou um comentário para ele é uma chave que o autor escreveu, e uma sincronização deixa-o byte a byte.
Envie sync para atualizar o que uma importação anterior redigiu em outputDir em relação à origem, alterando apenas o que a importação escreveu. Cada parte é avaliada de três formas — o que o histórico diz que a importação aí escreveu da última vez, o que está no disco e o que a origem redige agora. Uma parte que a origem deixou tal como a importação a escreveu da última vez fica exatamente como está no disco, quer um autor a tenha editado quer não. Uma parte que a origem alterou é escrita de novo, uma parte que deixou cair é removida — um ficheiro redigido é eliminado por inteiro — e uma parte que ganhou é acrescentada ao lado das partes que o rascunho indica à sua volta, cada uma apenas quando o que está no disco é o que a importação escreveu da última vez e não contém nada que um autor tenha acrescentado. Tudo o resto fica byte a byte: uma chave que um autor acrescentou em qualquer sítio — um parâmetro, uma Feature, também sob uma instância de Component redigida, outro Component — um comentário não escrito diretamente acima de uma chave redigida, e todos os ficheiros que o histórico não lista. Uma sincronização para um diretório sem histórico e sem nada nos seus caminhos redigidos escreve todo o rascunho, como faz um pedido sem sync.
drift é o que uma sincronização atualizou, e é a resposta a «a origem mudou?». Lista cada parte que a sincronização alterou — ou, com dryRun, cada parte que alteraria — pela ordem em que o rascunho as indica, cada uma como change (added, removed ou changed), file, o ficheiro redigido em que está, relativo a outputDir, e key, as chaves que conduzem a ela num Aggregate ou numa Release redigidos, como lista, pelo que uma chave que contenha um ponto final continua a ser uma única entrada; key fica vazio quando a parte é o ficheiro inteiro, que é como é indicado um ficheiro redigido que a sincronização elimina. aggrega import imprime as mesmas entradas no erro padrão como <change> <key> in <file> ou <change> <file>, e o seu estado de saída com --sync --dry-run diz se a origem divergiu; esta superfície não tem estado de saída, por isso envie sync com dryRun e leia se drift está vazio. drift é uma lista vazia para um pedido que não é uma sincronização, para uma sincronização em linha com a sua origem e para uma sincronização cujo importador não conseguiu terminar. Com sync, files contém cada ficheiro redigido que a sincronização altera, com o conteúdo que lhe dá, depois o histórico quando também este muda, e written indica os que chegaram ao disco — pelo que uma sincronização em linha responde a ambos como listas vazias. Um ficheiro redigido que a sincronização elimina é indicado em drift e em nenhuma das listas: a sua entrada removed, com uma key vazia, é o único relato que a resposta faz dele, com dryRun a indicar o ficheiro que uma escrita eliminaria.
Uma sincronização nunca reescreve o que um autor escreveu, e recusa em vez disso. Uma sincronização que alteraria ou removeria uma parte que um autor editou, acrescentaria uma parte onde um autor já escreveu uma, ou removeria uma parte que contém algo que um autor acrescentou é recusada, indicando cada uma dessas partes e o motivo numa linha própria, nas palavras que aggrega import --sync usa — <file> <key>: <why>, ou <file>: <why> para um ficheiro inteiro — e nada é escrito; um comentário escrito diretamente acima de uma chave redigida edita essa chave. Uma sincronização sobre um Aggregate que nenhum histórico lista é recusada indicando o Aggregate e o histórico, tal como uma cujo histórico não pode ser lido, uma vez que sem o histórico as suas partes não podem ser distinguidas das de um autor. Ambas as recusas regressam como o erro invalid-params, também com dryRun, e indicam sync. Reconcilie à mão cada parte indicada, ou reponha o que a importação aí escreveu, e envie o pedido de novo.
🔴 halted: true não é um erro, e tratá-lo como tal é o equívoco contra o qual desenhar. Um importador que não conseguiu converter tudo continua a redigir o que conseguiu: a resposta contém esses rascunhos, written indica-os e diagnostics diz o que ficou de fora. Essa é a resposta mais útil que a operação dá, e chega como resultado e não como falha precisamente para que possa mostrar ao autor ambas as metades. Com sync a mesma resposta não escreve nada — files, written e drift ficam vazios — porque um rascunho parcial pareceria uma origem que deixou cair todas as partes que o importador não alcançou. Uma origem que o importador não conseguiu ler de todo é um caso diferente e regressa de facto como erro.
Cada diagnóstico contém severity e message, mais code quando o importador atribuiu um. Ramifique com base em code quando quiser reagir a uma condição específica e mostre message ao leitor; severity é tirado do mesmo conjunto em que todos os sockets de plugin reportam — halt, warn, info — pelo que halted é um resumo das entradas e não um juízo separado. files, written, drift, diagnostics e decisions são sempre arrays, vazios em vez de ausentes.
decisions diz onde a importação adivinhou. Contém uma entrada por cada nó de origem que o importador mapeou, pela ordem do importador e exatamente como o importador a reportou: sourceNode, o id, type e paramsSummary do nó; candidates, cada Component do catálogo que o importador ponderou para ele como componentName, score, tier e signals — o que cada um dos seus sinais contribuiu, em table, category, domainLabels, shape e name; chosen, o target que escolheu, o mode em que o escreveu — uma reference a um Component existente ou um draft — e o tier da escolha; rationale, o porquê; e swapHint, como escolher de outra forma. candidates está ausente quando o importador não ponderou nenhum, chosen quando não fez nenhuma escolha, e rationale e swapHint quando não escreveu nenhum. Todos os valores são do próprio importador — como pontua um candidato e onde caem os seus níveis são escolhas suas — por isso mostre uma entrada como o relato dele sobre o mapeamento e não como um veredicto. As decisões chegam com dryRun e com halted true igualmente: as suposições de uma importação parcial são exatamente aquilo de que precisa um autor que a reveja, e um importador que não reporta nenhuma responde com uma lista vazia. Quando as mostrar como texto, aggrega import já formula uma decisão como mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, sendo a pontuação a do melhor candidato.
O formato é reconhecido a partir da origem, a menos que o indique. O reconhecimento usa as assinaturas que os importadores declaram — tanto as do catálogo do espaço de trabalho como as dos importadores nucleares do compilador — que a entidade Plugin de cada importador regista — a sintaxe em que uma origem é lida, os nomes de ficheiro a que uma assinatura se aplica e os caminhos que a árvore analisada tem ou não de conter — pelo que o próprio daemon não conhece nenhum formato e o formato de um novo importador é reconhecido sem mais nada alterado. A deteção lê apenas a origem que enviou — de um diretório, apenas os ficheiros que os padrões de ficheiros de uma assinatura selecionam — e nenhuma rede, analisando cada ficheiro que lê através do analisador que o catálogo do espaço de trabalho serve para uma sintaxe — ou, para uma sintaxe para a qual o catálogo não serve analisador, o que o próprio compilador contém — uma vez por cada sintaxe em que uma assinatura aplicável ao seu nome o lê; o importador lê então a origem através do mesmo analisador. Uma assinatura que não declara nenhum padrão de ficheiro aplica-se ao ficheiro que enviou, qualquer que seja o seu nome, e a nenhum ficheiro de um diretório; as assinaturas dos importadores Langflow, Flowise e n8n são desse tipo e leem JSON, e a do importador Dify lê YAML, pelo que reconhecer um ficheiro que enviou por si só lê-o como JSON e como YAML, o que não precisa de nenhum analisador no catálogo do espaço de trabalho: o compilador contém um analisador JSON e um YAML, e um que o catálogo sirva é usado no seu lugar. Uma origem a que nenhuma assinatura corresponde é recusada pedindo format e indicando os formatos que os importadores anunciam — ou, para um diretório, pedindo um dos seus ficheiros enviado por si só ou um format cujo importador declare padrões de ficheiros, indicando apenas esses — sob a condição No importer recognises the source (Nenhum importador reconhece a origem); uma origem a que correspondem assinaturas de mais de um formato é recusada indicando-os, sob a condição More than one importer recognises the source (Mais do que um importador reconhece a origem). O data de cada recusa contém o code e o shortCode da sua condição, pelo que um cliente pede o formato com base no código e não nas palavras. Nenhum dos dois é adivinhado, porque um formato adivinhado resolve o importador errado e produz disparates confiantes. format na resposta é o que foi usado, detetado ou indicado, pelo que um cliente que o omitiu fica a saber o que obteve.
Um diretório que envia é lido para os ficheiros que o seu importador indica, e um que não consegue ler é um erro. Quando source indica um diretório, o importador recebe os ficheiros dele que os padrões de ficheiros que as suas assinaturas declaram selecionam, excluída a pasta de saída da compilação da área de trabalho dist/, cada um indicado pelo seu caminho dentro do diretório, por ordem, ao lado dos ficheiros que a sua entrada plugins.importer indica em with.sources. Um importador que não declara nenhum padrão de ficheiro, um diretório que não contém nenhum ficheiro que estes selecionem, um ficheiro do diretório e um ficheiro de with.sources com o mesmo nome, e uma ligação simbólica entre os ficheiros que a importação leria, ou para um diretório, que conduza para fora do diretório regressam cada um como erro com o código da condição, sem nada escrito.
Que importador é executado é decisão do espaço de trabalho, não do pedido. O formato resolve para o importador que o anuncia entre os plugins do catálogo do espaço de trabalho e os importadores nucleares do compilador — aquele que uma entrada plugins.importer na configuração do espaço de trabalho anexa, quando anexa um deles — pelo que um pedido não pode selecionar um módulo nem apontar para um no disco. Um formato que nenhum importador anuncia é recusado indicando o formato, e um formato que dois importadores anunciam sem nenhum anexado — entre eles um importador nuclear e um importador de outro nome que o catálogo contém para o mesmo formato — é recusado como ambíguo em vez de resolvido arbitrariamente.
Um importador nuclear que a máquina ainda não tem é obtido uma vez, pela primeira importação que dele precisa. Vem do registo predefinido do espaço de trabalho, sujeito ao módulo que a versão do compilador publica e verificado como uma obtenção verifica um plugin que obtém — a sua assinatura segundo a política de confiança desse registo, e as funções de host que usa — e é mantido na cache de conteúdos do espaço de trabalho, que é a única coisa escrita para ele: nenhum lockfile e nenhum histórico de plugins de confiança. Todas as importações posteriores o leem daí e não acedem a nenhum registo. Um módulo que não verifica é um erro com o código da sua condição, e nada é mantido; um que não pode ser obtido — o espaço de trabalho está offline, o seu registo não pode ser alcançado ou o registo não o contém — é um erro sob A plugin’s .wasm is not on this machine (o ficheiro de um plugin não está nesta máquina), indicando o importador, a sua versão e o que coloca o seu módulo na máquina. O próprio pedido não indica nenhum registo, e uma importação com todos os importadores e o catálogo que lê na máquina não acede de todo à rede.
Quando o espaço de trabalho não indica nenhuma pasta de catálogo, a importação lê o catálogo que o seu registo predefinido publica. Um espaço de trabalho em que nem workspace.catalog_dirs, nem AGGREGA_CATALOG_DIRS, nem a raiz indicam uma pasta de catálogo lê o catálogo da biblioteca padrão como um único instantâneo assinado, em catalog/snapshot no seu registo predefinido. Um instantâneo é obtido uma vez: a sua assinatura é verificada segundo a política de confiança desse registo, e é mantido na cache de conteúdos do espaço de trabalho e lido aí como uma pasta de catálogo, vinculado ao seu digest, sem que nenhum registo volte a ser consultado para ele. Que instantâneo um pedido lê: com upgrade, o mais recente; caso contrário, o que o histórico em outputDir indica, obtido pelo seu digest quando a máquina não o tem; caso contrário, o que o espaço de trabalho obteve por último como o mais recente; caso contrário, o mais recente. O histórico que a importação escreve indica o instantâneo que leu, pelo seu digest, pelo que um pedido posterior no mesmo outputDir lê o mesmo catálogo. Na postura offline, um pedido que tivesse de obter um instantâneo é um erro sob The workspace is offline and the step needs the network (O espaço de trabalho está offline e o passo precisa da rede), indicando o que executar, e upgrade é recusado independentemente do que a máquina tenha, uma vez que só o registo pode dizer qual instantâneo é o mais recente. Um registo que não publica nenhum instantâneo deixa a importação sem catálogo, e uma entrada warn em diagnostics assinala-o. Um espaço de trabalho que indica uma pasta de catálogo importa com base nela e não obtém nenhum instantâneo, e upgrade não altera nada aí.
Com dryRun nada é criado. written fica vazio, files contém os mesmos ficheiros que uma escrita teria produzido — com sync, os ficheiros que a sincronização escreveria, ao lado do drift que atualizaria — e nenhum diretório é criado — pelo que um editor pode colocá-los diante do autor para guardar, alterar ou descartar. Tudo o resto que uma escrita faz é feito: o mesmo importador é executado sobre a mesma origem e reporta os mesmos diagnósticos, pelo que uma origem que uma escrita recusaria é aqui também recusada. Um importador nuclear ou um instantâneo do catálogo obtido com dryRun é mantido na cache de conteúdos tal como numa escrita, porque adquirir aquilo sobre o qual a importação é executada faz parte de a executar e não de colocar os rascunhos.
Um caminho que o importador devolve é mantido dentro de outputDir. Os caminhos dos rascunhos vêm do importador e não de si, pelo que um caminho que sobe para fora do diretório de saída é recusado e absolutamente nada é escrito — nem sequer os rascunhos cujos caminhos estavam bem. A recusa indica o caminho infrator, que é o que lhe diz que é o importador que deve ser corrigido e não o seu pedido.
A que pergunta responde cada pedido de entidade
Quatro pedidos aqui informam-no sobre uma entidade, e não são intercambiáveis. Escolher entre eles é uma questão do que tem em mãos quando pergunta.
Tem em mãos um cursor. aggrega/hover e aggrega/resolve recebem um ficheiro e uma posição e deduzem a que entidade se refere o que está aí escrito. Abrangem as formas de referência que um documento efetivamente contém — um valor extends, um tipo de componente ou de funcionalidade, o implements de uma Recipe, as referências a receitas de um Manifest, os dois ponteiros de caminho de uma Release, um alvo uses e o próprio metadata.name de uma entidade. Recorra a estes quando o cursor do utilizador é a coordenada: o utilizador está a ler um documento e quer saber para onde aponta uma referência.
Tem em mãos um nome. aggrega/entityDefinition recebe diretamente a identidade. Nada tem de estar aberto, nenhuma posição está envolvida, e a entidade não tem de ser mencionada em nenhum sítio que o cliente consiga encontrar. Recorra a ele quando o utilizador escreveu um nome, escolheu um de uma lista ou seguiu algo cuja identidade o seu próprio cliente já conhece — um hover exige que encontre primeiro um sítio onde o nome está escrito, o que é trabalho que não tem de fazer.
Ainda não tem nada em mãos. aggrega/catalogIndex enumera o que o espaço de trabalho contém, com os campos descritivos de cada entidade. Recorra a ele para preencher um seletor, e depois passe um nome escolhido a aggrega/entityDefinition.
Tem em mãos uma Release. aggrega/releaseClosure responde sobre uma Release e não sobre uma entidade, e é a secção abaixo.
A definição que um pedido por nome devolve é a entidade tal como resolvida, não como qualquer ficheiro a declara. Um Component ou uma Feature que estende uma base regressa com o contrato dessa base, que não aparece em lado nenhum no documento que declara o seu nome — pelo que a resposta é sobre o que a entidade é, e ler o ficheiro por si não lhe daria a mesma coisa.
Chega como documento YAML e não como estrutura dentro da resposta, e isso é deliberado: um pilar de esquema tem várias formas de autoria — conteúdo escrito por extenso, uma referência a um documento partilhado, ou o marcador que diz que o conteúdo vem de uma base — e o documento reproduz aquela a que a resolução chegou, pela ordem de chaves do próprio autor. Analise-o como documento se precisar dos seus campos; mostre-o tal como está se o estiver a colocar num painel.
Distinguir as duas recusas por nome
Um nome que não resolve para nada é recusado em vez de respondido com um documento vazio, porque uma resposta vazia reportaria um erro de escrita como uma entidade sem nada a dizer sobre si. Há duas formas de um nome não resolver para nada, que exigem coisas diferentes do leitor, e distingue-as pelo que o data do erro contém, não lendo a mensagem:
- Nenhum
fileemdata. Nada no espaço de trabalho declara esse nome e nenhum nível do catálogo o resolve. Isto é quase sempre o pedido a corrigir — um erro de escrita, ou um nome de um catálogo que este espaço de trabalho não tem no seu caminho de pesquisa. - Um
fileemdata. Um documento do espaço de trabalho declara de facto esse nome, e mesmo assim o catálogo não resolveu nada para ele. A entidade está escrita e algo a recusou, o que é um estado do espaço de trabalho que uma pessoa repara. Quando exatamente um documento que o catálogo leu e recusou declara esse nome — a causa habitual — a mensagem começa por essa recusa, indicada uma vez: a sua categoria e código curto, o documento pelo caminho em que é reportado, e o que está errado nele, como a linha e a restrição que viola; depois nota que o ficheiro foi ignorado no carregamento, e lista qualquer outro ficheiro que o carregamento recusou. Caso contrário, a mensagem indica o documento declarante, lista os ficheiros que o carregamento recusou e diz de onde este espaço de trabalho lê entidades locais e o que alterar para que o documento seja lido — o relato que omite quando um documento recusado declara o nome, porque esse documento já está onde o catálogo lê.
Ambas contêm o código entity-not-resolvable, por isso ramifique com base na presença de file e não no código.
Perguntar sobre uma coordenada
Tem em mãos uma referência de registo. Envie-a como o name de aggrega/entityDefinition, e a resposta é a entidade publicada nessa coordenada, na mesma forma de resultado que um nome obtém mais published, preenchida a partir do que foi publicado e não do que um catálogo resolveu:
definitioné o documento de entidade exatamente como foi publicado. Uma coordenada cuja entidade foi publicada com os ficheiros que declara contém um arquivo, e o documento é extraído dele; uma cuja entidade não declara nenhum ficheiro contém o seu documento sem alterações, e a entidade de um Plugin é lida do seu manifesto e não do executável publicado com ele. Não é aplicada nenhuma herança.authoredLengthé o comprimento desse documento, porque a definição aqui é um documento de autoria e não uma renderização de um resolvido.fileestá vazio, porque uma entidade lida de um registo não tem nenhum documento nesta máquina a indicar.publishScopeé omitido: já tem a coordenada, que é onde a entidade está publicada.publishedé o que foi lido, e está presente nesta resposta e em nenhuma por nome: areference;archive, se os seus bytes eram um arquivo do qual o documento foi extraído —falsequando a coordenada continha o próprio documento; omediaTypeque o manifesto declara; e omanifestDigestdesse manifesto, que pode enviar depois de@em vez da tag para voltar a ler exatamente os mesmos bytes.
O pedido acede ao registo que a referência indica, com as credenciais do utilizador com que este daemon é executado e a postura de rede deste espaço de trabalho, pelo que um espaço de trabalho offline o recusa. Os bytes obtidos são verificados com o digest que o próprio manifesto do artefacto regista para eles e com mais nada — nenhuma assinatura é verificada e nenhuma retirada é reportada — e nada é escrito. Uma referência que não pode ser lida é recusada com entity-not-resolvable, e a mensagem abre com o código curto da condição que diz porquê — as mesmas condições que aggrega inspect reporta — e termina com o que fazer a esse respeito. Uma referência que não indica nenhum repositório, ou nem uma tag nem um digest, é um pedido mal formado e é recusada como parâmetros inválidos.
Um fecho não é o grafo
aggrega/irGraph e aggrega/releaseClosure são derivados da mesma resolução da mesma Release e respondem a perguntas diferentes. Um cliente que já recebe o grafo pode razoavelmente supor que também tem este, e não tem.
O grafo diz o que a Release implanta — os seus nós, as fronteiras em que estão, o que está ligado a quê, e os valores e anexos que cada nó contém. É a imagem.
O fecho diz o que foi trazido para a construir, e em que versões. Todas as entidades que a Release alcança, quer se tenham tornado nós quer não; os documentos partilhados de que essas entidades se servem; e os plugins que moldam o resultado. É a lista de materiais.
Nenhum é recuperável a partir do outro. Uma entidade pode ser alcançada sem nunca aparecer como nó — a Recipe para a qual um Manifest mapeia um tipo de componente é alcançada por todas as compilações e não é nó em nenhuma delas — e um nó não contém a versão para a qual o seu tipo resolveu. Assim, um leitor que pergunte «porque mudou esta versão?», «o que afetaria alterar este documento partilhado?» ou «de que depende realmente esta Release?» está a pedir o fecho, e um leitor que pergunte «o que implanta esta Release?» está a pedir o grafo.
O que o pedido de fecho não faz. Não renderiza nada e não publica nada do que encontra. Em particular, não levanta nenhum aviso de desvio nem nenhum aviso de renderização: esses pertencem ao pedido que os solicitou, e publicar substitui uma camada inteira de diagnósticos, pelo que uma listagem que publicasse apagaria o que o pedido de grafo já tinha colocado diante do utilizador. Peça o grafo quando quiser o veredicto de desvio. A única coisa que publica não é uma constatação sua: um pedido que encontre o lockfile desaparecido retira o aviso de desvio que estava sobre ele, seja qual for o pedido — consulte Consciência do lockfile.
Requer um lockfile, tal como o grafo. As versões que a listagem reporta são aquelas para as quais esta Release resolveu, e um espaço de trabalho que ninguém preparou ainda não as resolveu. Uma listagem produzida sem um reportaria o que o catálogo por acaso contém hoje, o que é uma pergunta diferente de saber de que depende esta Release. A recusa indica o lockfile e a Release, para que um cliente possa oferecer diretamente aggrega pull --release <release>.
kind numa entrada do fecho está presente apenas quando é conhecido. Uma referência é recolhida de uma posição num documento, e algumas posições dizem para que tipo apontam enquanto outras não. O campo é reportado quando o local da referência registou um e omitido quando não registou, em vez de ser adivinhado a partir da forma do nome. É reportado como a palavra que um autor escreve no início de um documento, que é a mesma palavra que todas as superfícies que reportam um fecho usam para a mesma entrada.
A mesma palavra pede o mesmo documento noutros sítios. aggrega inspect <release> --closure responde a esta pergunta na linha de comandos, e o modo de versão da ferramenta describe responde-lhe através do protocolo de ferramentas do assistente. Os três executam uma única resolução sobre a Release, pelo que não podem vir a discordar sobre aquilo de que uma Release depende. Consulte aggrega inspect «O fecho de dependências».
Modelo de cache
As operações são orientadas pela cache: chame aggrega/validate para um ficheiro antes de hover / completion / resolve / diagnostics sobre ele. Essa chamada de sementeira não precisa de uma Release — uma validação que não indique nenhuma continua a analisar o buffer e a preencher a cache — pelo que estas operações funcionam num espaço de trabalho que não tem nenhuma Release a indicar. A cache de análise é verificada com a hora de modificação de cada ficheiro no disco em cada leitura, pelo que as edições externas (uma gravação no editor, um git checkout) são detetadas automaticamente — o aggrega/invalidate do editor é uma otimização, não um requisito de correção.
A cache pertence ao espaço de trabalho que a semeou. Um ficheiro validado num espaço de trabalho fica em cache para esse espaço de trabalho, pelo que o mesmo caminho perguntado noutro é reportado como ainda não validado em vez de ser respondido a partir da entrada do primeiro. É isso que impede que uma pergunta sobre um segundo espaço de trabalho responda mal ou custe ao primeiro o seu estado aquecido — e aggrega/invalidate também limpa apenas o espaço de trabalho que indica.
Pedir diagnósticos enquanto uma validação está em curso
Uma validação semeia duas coisas sobre um ficheiro — a análise que entrega às outras operações e as constatações que reporta — e semeia-as com um momento de intervalo. aggrega/diagnostics é o único pedido que lê ambas: precisa da análise para saber que o ficheiro é um sobre o qual pode responder, e responde a partir das constatações. Assim, um pedido que chegasse entre esses dois momentos estaria a decidir que pode responder quando ainda não há nada com que responder.
Em vez disso, espera. Envie aggrega/diagnostics para um ficheiro que está a ser validado neste momento e a resposta chega quando essa validação termina, com o que encontrou. Há uma única resposta correta para o ficheiro, qualquer que seja o momento, e é essa a resposta que obtém — nunca é uma lista vazia para um ficheiro cuja validação está prestes a reportar erros, que é a única resposta errada de que um cliente não consegue recuperar, porque nada o leva a perguntar de novo sobre um ficheiro que lhe disseram estar limpo. As outras operações baseadas em posição — hover, completion, resolve, findReferences, findImplementations — leem a análise e respondem a partir dela, pelo que não têm nada por que esperar e nunca esperam.
Duas coisas terminam a espera mais cedo, e ambas são coisas que já tem. $/cancelRequest para o id desse pedido interrompe-o, e um aggrega/shutdown cooperativo interrompe-o. Nenhuma das duas precisa de nada extra no pedido.
E a espera é limitada. Se a validação não tiver terminado dentro do orçamento do daemon para ela, o pedido é recusado com o código validation-in-flight em vez de ser respondido vazio — consulte Códigos de erro. Essa recusa significa que o trabalho por que está à espera está realmente em curso, pelo que o que há a fazer é perguntar de novo pouco depois; não é um sinal para enviar outra validação, o que acrescentaria trabalho e não responderia a nada.
Um daemon que executa os pedidos um de cada vez responde-lhes por ordem de chegada, pelo que nada se sobrepõe e nunca há espera. Um daemon que os executa em simultâneo responde às mesmas perguntas da mesma forma, e a espera é o que torna isso verdade: a resposta que obtém é a resposta que uma ordenação em série lhe teria dado.
Tamanhos numa resposta
Uma resposta que reporta uma quantidade de bytes reporta-a duas vezes: como número e como a mesma quantidade escrita por extenso. O campo escrito é o nome do campo numérico com Text acrescentado — size e sizeText, totalSize e totalSizeText, reclaimedBytes e reclaimedBytesText, e assim por diante em todas as respostas que contêm um tamanho.
Apresente a forma escrita e calcule com o número. O objetivo de enviar ambos é que um cliente nunca tenha de escrever um tamanho por si: o daemon escreve-o com o mesmo formatador que a linha de comandos usa, pelo que aggrega cache status e aggrega/cacheStatus mostram uma dada cache de forma idêntica, até ao arredondamento. Um cliente que compusesse o seu próprio texto divergiria disso na primeira vez que discordasse sobre um limite.
A forma escrita usa unidades binárias — 512 B, 1.0 KiB, 5.0 MiB, 3.0 GiB — que é o mesmo vocabulário que aggrega/cacheEvict aceita em maxSize, pelo que um tamanho lido de uma resposta pode ser enviado de volta no pedido seguinte sem ser reescrito. Acima dos bytes o texto tem uma casa decimal, pelo que indica a quantidade como um leitor a quer ver e não ao byte; quando precisar da contagem exata, é para isso que serve o campo numérico.
Quando o número é opcional o texto é opcional com ele, e os dois nunca estão presentes pela metade: o tamanho do plugin numa resposta de publicação contém pluginSize e pluginSizeText em conjunto ou nenhum dos dois.
Cada pedido indica o espaço de trabalho a que se refere
Envie workspaceRoot em todos os pedidos: o caminho absoluto da raiz do espaço de trabalho sobre a qual esse pedido atua. O daemon não detém nenhum espaço de trabalho próprio e não se lembra de nenhum entre pedidos, pelo que aquilo sobre que um pedido é respondido é o espaço de trabalho que indicou e mais nada. Dois pedidos que indiquem dois espaços de trabalho obtêm duas respostas, e nenhum consegue ver as entidades, Releases, análises em cache ou diagnósticos do outro.
Um pedido que não indique nenhum é recusado com o erro invalid-params padrão que indica o parâmetro, e o mesmo acontece com um valor vazio, que não declara nenhum espaço de trabalho e recebe a mesma resposta que um em falta. Outras duas formas são recusadas pela mesma razão, cada uma indicada na mensagem: um caminho relativo, porque uma raiz de espaço de trabalho não tem nada em relação a que ser relativa; e um caminho que não é um diretório existente, porque um espaço de trabalho é uma árvore.
Três pedidos não precisam de workspaceRoot, e cada um porque o seu sujeito não é um espaço de trabalho. aggrega/getSchema e aggrega/scaffoldEntity respondem a partir dos esquemas compilados no binário em execução, pelo que um espaço de trabalho não contribui com nada para nenhum deles — o que permite a ambos responder num diretório que ninguém preparou. aggrega/initialize é o terceiro, e é onde declara um espaço de trabalho em vez de atuar sobre um. A outra forma de aggrega/scaffoldEntity, que escreve ou lista os exemplos executáveis da documentação, atua de facto sobre um espaço de trabalho, e um pedido para ela indica um como qualquer outro.
O estado em cache de cada espaço de trabalho é mantido separadamente, e indicar um segundo não custa nada ao primeiro. O índice do catálogo, a cache de análise e os diagnósticos de um espaço de trabalho pertencem a esse espaço de trabalho, pelo que uma pergunta feita sobre outro sítio não expulsa o que um editor tem vindo a acumular para a pasta que alguém tem aberta. Duas formas de escrever uma raiz são um único espaço de trabalho, pelo que um caminho com um . interior ou um separador duplicado chega ao mesmo estado aquecido que a sua forma simples.
Declarar o espaço de trabalho para o qual quer que os diagnósticos sejam enviados
Os diagnósticos viajam de duas formas: pede-os, ou o daemon envia-os por iniciativa própria. O daemon só os envia para o espaço de trabalho que declarou no handshake. Todos os outros pedidos respondem com as suas constatações na sua própria resposta e não enviam nada.
Declare-o enviando workspaceRoot em aggrega/initialize. Isso é tudo o que a declaração faz — não ancora nada, e nenhum pedido posterior é respondido em relação a ela.
A razão para o limitar é a finalidade de um diagnóstico enviado. Enviar é o que mantém atualizada a lista de problemas de um editor enquanto alguém escreve, e é exatamente a coisa errada a fazer com uma resposta que ninguém pediu para ver: sem a regra, uma pergunta feita sobre um segundo espaço de trabalho — por outra ferramenta que partilhe o daemon, por exemplo — encheria a lista de problemas de um leitor com constatações sobre ficheiros que nunca abriu. Limitar o envio mantém a pergunta de quem chama fora da lista de problemas de outro.
O campo é opcional, e as três coisas que pode querer dizer com ele são distinguíveis:
| o que envia | para onde vão os envios | o que o handshake reporta |
|---|---|---|
| nada | o espaço de trabalho sobre o qual o processo foi lançado | esse espaço de trabalho |
| uma raiz de espaço de trabalho | esse espaço de trabalho | esse espaço de trabalho |
| a cadeia vazia | para lado nenhum — nenhum diagnóstico é alguma vez enviado | uma raiz vazia |
Não enviar nada deixa os envios no espaço de trabalho sobre o qual o processo foi iniciado, pelo que um cliente que não declare nada recebe os diagnósticos desse espaço de trabalho. Enviar a cadeia vazia é a declaração honesta para quem chama e não é um editor nem tem nenhuma lista de problemas a manter sincronizada: todas as constatações continuam a chegar-lhe, na resposta ao pedido que as produziu.
Um espaço de trabalho declarado é resolvido exatamente como um indicado num pedido, pelo que uma declaração que indique um caminho relativo, ou um caminho que não é um diretório, é recusada no handshake em vez de deixar os envios apontados para um sítio inesperado.
Raiz do espaço de trabalho e Release ativa
O daemon resolve cada espaço de trabalho que um pedido indica da mesma forma que todos os comandos aggrega resolvem um, e Configuração indica o que ancora uma raiz e por que ordem. Duas consequências importam a um cliente. Um .aggrega-config.yaml sem um bloco workspace: não ancora: continua a contribuir com as suas definições, mas um simples ficheiro de definições não pode transformar todos os diretórios pais numa raiz de espaço de trabalho. E quando nada ancora, é usado o diretório de trabalho — o daemon arranca e as operações simplesmente não resolvem nada, em vez de se recusarem a ser executadas.
O processo é também lançado sobre um espaço de trabalho, a partir de --workspace-root ou subindo a partir do seu diretório de trabalho, e essa resolução faz duas coisas e mais nenhuma: dimensiona o conjunto de workers, que é uma propriedade do processo e não de nenhum pedido, e é a declaração predefinida para os diagnósticos enviados. Nenhum pedido é respondido em relação a ela.
A configuração é igualmente a mesma cascata que todos os comandos leem, e Configuração é onde é descrita. O que o daemon acrescenta é apenas que a leitura que cada espaço de trabalho faz dela é feita uma vez, quando esse espaço de trabalho é indicado pela primeira vez, e reutilizada em todos os pedidos posteriores sobre ele. Um ficheiro de configuração que essa cascata leria e que é uma ligação simbólica que conduz para fora do espaço de trabalho — o próprio .aggrega-config.yaml do espaço de trabalho, ou a sobreposição detida pela CI ao lado dele — não é lido, aqui como num terminal, e nada mais que esse ficheiro teria configurado é lido no seu lugar. O que difere de um terminal é o que continua a responder. O daemon lançado sobre um tal espaço de trabalho arranca, e di-lo uma vez no seu fluxo de erro; um pedido que indique um é respondido da seguinte forma em qualquer dos casos. aggrega/releaseCandidates e aggrega/catalogIndex — os dois pedidos que listam o que um espaço de trabalho contém — respondem-lhe, lido sem nada configurado: os documentos próprios do espaço de trabalho são listados, nenhum diretório de catálogo é lido, e o ficheiro retido é indicado em unreadLinkedFiles, quer a pesquisa o tenha encontrado quer não. Esse nome é como um cliente percebe que a configuração do espaço de trabalho conduz para fora dele. Todos os outros pedidos que indicam o espaço de trabalho — uma compilação, um grafo, uma validação, a Release predefinida, a configuração efetiva, uma escrita, e aggrega/catalogIndex nos termos de uma Release — são decididos por essa configuração, pelo que são recusados com o erro invalid-params que contém E0321 — read-leads-out-of-workspace no data do erro — e a frase que indica a ligação simbólica e para onde conduz. O handshake também responde por um tal espaço de trabalho, reportando defaults como o seu configSource, uma vez que nenhum ficheiro de configuração contribuiu com nada com que as listagens respondam. Remova a ligação simbólica, ou faça-a conduzir a um ficheiro dentro do espaço de trabalho, e o pedido seguinte lê a configuração. Por baixo dos ficheiros do projeto fica a camada global: o ficheiro que --config indica na linha de comandos que iniciou o daemon, para todos os espaços de trabalho que serve; caso contrário, o ficheiro que a variável de ambiente AGGREGA_CONFIG indica quando está definida; e caso contrário a localização predefinida — no Windows aggrega\config.yaml dentro do diretório que a variável de ambiente APPDATA indica, e noutros sistemas aggrega/config.yaml dentro do diretório que XDG_CONFIG_HOME indica, recorrendo a ~/.config/aggrega/config.yaml — carregada quando presente. As predefinições incorporadas ficam por baixo disso.
As operações que atuam sobre uma Release recebem-na como parâmetro; o daemon não seleciona nenhuma por si. Um espaço de trabalho continua a declarar para que Release aponta, e uma cascata de quatro passos lê essa declaração: o campo de configuração build.authoring_release, depois um ficheiro marcador .aggrega/active-release, depois uma heurística de uma única Release no espaço de trabalho, depois um recurso apenas de Aggregate. Um marcador que escreva tem assim precedência sobre a heurística, e um marcador que indique uma Release que não pode ser carregada passa à heurística e não ao recurso. Um marcador que indique uma Release fora do espaço de trabalho — por um caminho absoluto, por um caminho que sobe para fora da raiz, ou através de uma ligação simbólica que conduz para fora dela — não é lido, a menos que a configuração do seu espaço de trabalho indique essa Release como build.authoring_release ou como chave de workspace.releases: a configuração é a forma de alcançar uma Release mantida fora do espaço de trabalho, e o marcador não. A cascata avança então exatamente como para um marcador que não consegue carregar e, quando não se fixa em nada, trace diz porquê na linha do marcador e reason na sua frase sobre o marcador.
aggrega/activeRelease reporta o que essa cascata escolhe, e é uma sugestão para um cliente e não uma definição com base na qual o daemon atua. Pergunte ao daemon em vez de ler por si as entradas da cascata: o campo de configuração e o ficheiro marcador são duas de quatro entradas, pelo que qualquer uma que leia só indica a escolha do espaço de trabalho quando por acaso é a entrada que ganhou. Um marcador que indique uma Release que não pode ser carregada é o caso mais claro — a cascata escolhe uma Release completamente diferente, e quem lesse o marcador reportaria a que falhou.
A cascata é executada quando pergunta e não antes, o que tem duas consequências em que vale a pena confiar. O handshake mantém-se rápido qualquer que seja o tamanho da árvore, porque não espera pelo percurso do espaço de trabalho. E a resposta acompanha o espaço de trabalho: escreva um marcador — com aggrega/setActiveRelease, que responde com a própria nova escolha — edite a configuração, acrescente ou remova um ficheiro de Release, depois pergunte de novo, e obtém a nova resposta do mesmo daemon. Mudar a Release em que trabalha nunca exige reiniciar o daemon — um cliente envia uma release diferente no pedido seguinte.
As operações que pesquisam todo o espaço de trabalho em vez de um buffer — completion, hover, resolve, findReferences e findImplementations — enumeram o YAML sob a raiz do espaço de trabalho, e essa enumeração respeita .gitignore. Cada .gitignore desde a raiz do espaço de trabalho até ao próprio diretório do ficheiro contribui, ganhando o mais próximo, pelo que um ficheiro YAML que o seu repositório ignora não é oferecido como candidato de completação e não é reportado como definição ou referência. Um .gitignore que é uma ligação simbólica que conduz para fora do espaço de trabalho não é lido, pelo que um ficheiro noutro sítio da máquina nunca decide que documentos do espaço de trabalho são pesquisados. Árvores incluídas de terceiros e resultados gerados ficam assim fora dos resultados entre ficheiros sem nenhuma definição de exclusão separada a manter — e um documento que espera encontrar mas que ignorou não aparecerá, que é o único caso a verificar quando parece faltar uma referência. Os Components e as Features que completion também oferece a partir dos seus catalog_dirs configurados são uma leitura diferente: vêm desses diretórios tal como configurados — os mesmos diretórios que uma compilação de uma Release lê quando a configuração não dá a essa Release nenhuns próprios, ou, para um pedido que indique uma Release, os dessa Release — pelo que as entidades de um diretório de catálogo são oferecidas quer um .gitignore o abranja quer não — exceto uma entidade por trás de uma ligação simbólica que conduz para fora do diretório dentro do qual as leituras de um diretório de catálogo têm de ficar, que não é lida nem oferecida.
Um pedido que indica uma Release lê os diretórios de catálogo dessa Release, que são os que uma compilação dela num terminal lê: os seus próprios, quando a configuração do espaço de trabalho lhe dá alguns em workspace.releases, e os catalog_dirs do espaço de trabalho caso contrário. Isso abrange aggrega/build, aggrega/buildPreview, aggrega/irGraph, aggrega/releaseClosure, aggrega/resolveDependencies, aggrega/validate e aggrega/lint quando indicam uma Release, aggrega/attachCandidates e aggrega/attachmentContainer endereçados a um nó do grafo de uma Release, e aggrega/connectionAtPosition, bem como os pedidos que a secção seguinte lista quando indicam uma. Assim, uma única sessão responde a cada Release de um espaço de trabalho que mantém uma variante de catálogo por Release, cada uma a partir da sua própria variante, sem nada enviado além do caminho da Release. Um pedido que não diz respeito a nenhuma Release em particular — aggrega/catalogIndex, aggrega/entityDefinition, completion, hover e resolve quando não indicam nenhuma Release, e aggrega/attachCandidates endereçado a uma entidade ou a um conjunto de etiquetas — lê os catalog_dirs do espaço de trabalho. aggrega/lint que não indique nem uma entidade nem uma Release é a exceção num espaço de trabalho que indica Releases em workspace.releases: aí verifica todo o catálogo uma vez por cada Release, cada passagem sobre os diretórios dessa Release, como descreve Convenções de publicação, a pedido e em cada edição. Consulte Dar a uma Release os seus próprios diretórios de catálogo.
Responder nos termos de uma Release
aggrega/catalogIndex, aggrega/entityDefinition e os cinco pedidos que partem de um cursor — aggrega/hover, aggrega/resolve, aggrega/completion, aggrega/findReferences e aggrega/findImplementations — não dizem respeito a nenhuma Release em particular, e cada um aceita uma release opcional que o faz dizer respeito a uma. É um caminho relativo à raiz do espaço de trabalho, sujeito ao mesmo contrato a que os outros pedidos que aceitam uma Release o sujeitam; um valor que não indique nenhum ficheiro de Release, ou que indique um diretório, é recusado em vez de ser respondido nos termos do espaço de trabalho parecendo ser nos da Release.
O que uma Release alcança, para todos os pedidos aqui: os documentos do espaço de trabalho sob os diretórios de catálogo que a sua pilha lê, e todos os documentos do espaço de trabalho sob nenhum diretório de catálogo — uma Release, o seu Aggregate e o seu Manifest escritos ao lado dos catálogos. Um documento do espaço de trabalho sob um diretório de catálogo que só outras Releases leem não faz parte da sua resposta: não é listado, não é resolvido, não é oferecido. É isso que impede que variantes de uma entidade, mantidas lado a lado para Releases diferentes, sejam confundidas.
- A listagem. Indicar uma Release lista as entidades que essa Release vê. As Features listadas são as que os diretórios de catálogo dessa Release declaram, e um documento do espaço de trabalho sob um diretório de catálogo que só outras Releases leem fica de fora — pelo que um espaço de trabalho que mantém uma variante de uma entidade por Release lista a única variante com que essa Release compila, em vez de todas as variantes lado a lado. Um documento sob nenhum diretório de catálogo, como uma Release, o seu Aggregate e o seu Manifest escritos ao lado dos catálogos, pertence à listagem de cada Release.
- Uma consulta por nome. Indicar uma Release resolve o nome através dos diretórios de catálogo dessa Release, pelo que um nome que várias variantes declaram resolve para a variante com que essa Release compila. Um nome que os seus diretórios não resolvem é recusado com um relato que indica a entrada dessa Release em
workspace.releases, uma vez que essa entrada é o que a consulta leu. Uma referência de registo não aceita Release, e é recusada com uma: é lida do registo que a publica, qualquer que seja a Release indicada. - Hover e ir para a definição. Indicando uma Release, a referência no cursor é primeiro resolvida através dos diretórios de catálogo dessa Release, pela ordem que a configuração do espaço de trabalho lhes dá — a mesma resolução que uma consulta por nome nos termos dessa Release efetua — pelo que a entidade mostrada, e o documento aberto, é a variante para a qual esses diretórios a resolvem, mesmo quando um documento do espaço de trabalho noutro sítio declara o mesmo nome. Só quando nenhum documento sob esses diretórios responde por ela são pesquisados os documentos do espaço de trabalho que essa Release alcança. Não indicando nenhuma, a ordem é a inversa: os documentos do espaço de trabalho são pesquisados primeiro, pelo que uma referência a que um documento do espaço de trabalho responde mantém essa resposta, e os
catalog_dirsdo próprio espaço de trabalho só são consultados quando nenhum documento declara o nome — que é o que encontra uma entidade que só um diretório de catálogo configurado contém, incluindo uma fora da árvore do espaço de trabalho. Quando o editor tem uma cópia não guardada do documento para o qual os diretórios de uma Release resolvem, e essa cópia ainda declara o nome, a resposta é lida da cópia, pelo que uma posição cai na linha que o editor mostra. - Completação. Indicando uma Release, os nomes oferecidos são os que declaram os documentos do espaço de trabalho que essa Release alcança, juntamente com os Components e as Features que os diretórios de catálogo dessa Release declaram.
- Referências e implementações. Indicando uma Release, uma localização num documento do espaço de trabalho que essa Release não alcança não é reportada, pelo que uma variante mantida para outra Release nunca é listada como referência ou implementação desta.
- O que se pode anexar a um nó do grafo.
aggrega/attachCandidatesendereçado a um nó do grafo de uma Release é sempre nos termos dessa Release — consulte O que uma resposta de candidatos a anexo lhe diz.
Não indicando nenhuma, responde sobre os diretórios de catálogo do próprio espaço de trabalho, como descreve o parágrafo acima.
Aceder a um registo e escrever
A maioria dos pedidos aqui responde a partir do espaço de trabalho e do que já está em cache, e não escreve nada. Alguns, nomeados, fazem mais, e dividem-se segundo dois eixos independentes: o que um pedido alcança, e até onde vai o que altera.
Os pedidos que vão a um registo dividem-se entre os que leem e os que publicam. aggrega/resolveDependencies obtém aquilo de que uma Release precisa, e aggrega/build junta-se-lhe quando — e apenas quando — o seu campo autoPull lhe pede que resolva primeiro as dependências, caso em que acede a um registo e escreve o lockfile antes de renderizar; aggrega/registryUpdate percorre todos os registos configurados para reconstruir o índice de pesquisa local; aggrega/pluginAdd procura no registo configurado o plugin que um pedido indica e lê as suas versões publicadas para fixar uma; aggrega/registryAdd pede ao registo que adiciona a política de confiança que esse registo anuncia, a menos que o pedido recuse a obtenção ou forneça uma política própria, e aggrega/configInit pede o mesmo ao registo que está a semear; aggrega/explainError adquire o pacote de documentação a partir do qual lê o passo a passo de uma condição, uma vez, quando a cache que todos os projetos da máquina partilham não contém nenhuma cópia que a própria verificação de assinaturas do espaço de trabalho admita — consulte aggrega explain; aggrega/scaffoldEntity enviado com example ou list adquire o mesmo pacote nas mesmas condições, e uma escrita escreve então o exemplo num novo diretório do espaço de trabalho; aggrega/import obtém um importador nuclear do registo predefinido do espaço de trabalho, uma vez, quando a máquina ainda não o tem, e, num espaço de trabalho que não indica nenhuma pasta de catálogo, o instantâneo publicado do catálogo que lê — consulte O que uma resposta de importação lhe diz; e aggrega/entityDefinition lê a entidade que uma referência de registo indica quando uma é enviada como o seu name, sem escrever nada. aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts e aggrega/deprecateArtifact escrevem num — bytes, uma assinatura ou um marcador de retirada. Um pedido só acede a um registo quando foi enviado para isso: uma listagem reporta o que a configuração fixa, uma pesquisa lê um instantâneo offline, e uma publicação pedida com dryRun calcula o que enviaria e não contacta ninguém.
A regra é sobre quando uma operação é executada, não sobre que superfície a executa. Uma operação que obtém ou escreve é executada porque um pedido a indicou, e nunca como efeito secundário de validar um documento, inspecionar um grafo ou listar as entidades de um espaço de trabalho. Assim, um editor que valida a cada tecla premida não acede à rede nem reescreve nenhum lockfile, enquanto uma ação «resolver dependências» em que o utilizador clica faz exatamente o que aggrega pull faz — a mesma resolução, por trás de ambas as superfícies, escrevendo um lockfile idêntico byte a byte e preenchendo a mesma cache de artefactos.
Nada é solicitado interativamente. Ninguém está a ver este fluxo, pelo que a identidade é resolvida a partir de uma fonte de credenciais fornecida ou do ambiente e nunca perguntando. Onde o comando de terminal teria feito uma pergunta a uma pessoa — um registo que precisa de credenciais, uma capacidade que mais de um plugin de fornecedor serve, o texto que uma retirada deve conter — o pedido falha com uma mensagem que indica o que fornecer em vez de bloquear à espera de uma resposta que nunca chegará. Uma recusa deixa o espaço de trabalho exatamente como estava: nenhum lockfile é escrito e não fica nenhum dado parcial, e uma publicação que não conseguiu resolver uma credencial recusa antes de quaisquer bytes chegarem ao registo.
Algumas alterações vão além deste espaço de trabalho, e a resposta diz quais
Um pedido indica um espaço de trabalho, pelo que uma resposta sem nada a dizer sobre o seu próprio alcance é lida como sendo sobre esse espaço de trabalho. Para vários destes pedidos essa leitura estaria errada, pelo que cada um contém o seu âmbito e um cliente deve mostrá-lo antes de agir com base no resultado.
Publicar, assinar e retirar vão totalmente além da máquina, que é o maior alcance que algo aqui tem. As outras escritas abaixo alteram o que esta máquina resolve; estas alteram o que todos os que resolvem a partir desse registo fazem. Os bytes publicados são o que todos os consumidores desse registo obtêm, e voltar a publicar conteúdo diferente sobre uma tag é recusado em vez de oferecido, pelo que nenhum pedido aqui anula uma publicação — a resposta é publicar uma nova versão. Uma assinatura e um marcador de retirada são anexados como irmãos do artefacto em vez de o substituírem, pelo que os próprios bytes ficam intactos; mas quem obtiver o artefacto depois obtém-nos também, e nenhum dos dois pode ser recuperado de quem já o tem. Uma retirada é a mais fácil das três de ler mal: a versão continua a poder ser obtida, enquanto uma retração em que um espaço de trabalho confia a retira daquilo que uma resolução aí escolherá.
Assinar usa credenciais, e convém saber de onde vêm antes de ligar um cliente. A assinatura sem chave resolve um token de identidade, por ordem, a partir de identityToken no pedido, depois AGGREGA_IDENTITY_TOKEN no ambiente do daemon, depois o endpoint OIDC ambiente do GitHub Actions quando um está acessível, depois SIGSTORE_ID_TOKEN. Quando nenhum destes dá um token, a operação recusa e indica o que enviar; nunca abre um navegador, porque não há ninguém para o ver. A assinatura com chave é a alternativa offline, e um pedido não indica nenhum caminho de chave: o que um pedido lê está localizado dentro do espaço de trabalho que indicou, e uma chave privada nunca é mantida dentro de um espaço de trabalho, pelo que a chave vem do bloco signing: da própria configuração desse espaço de trabalho. Consulte aggrega sign para os dois modos de assinatura e o que cada um contacta.
Cada uma das quatro respostas contém reach, que contém registries — cada anfitrião de registo que a chamada endereçou, cada um indicado uma vez, pela ordem em que a chamada o endereçou pela primeira vez, pelo que um lote de assinatura ou um ficheiro de lote cujas referências abrangem vários registos indica cada um deles — e beyondThisMachine, que é derivado do que a chamada efetivamente anexou e não do que pediu: verdadeiro exatamente quando carregou conteúdo ou anexou uma assinatura, uma data de publicação ou um marcador de descontinuação, e falso para uma execução de ensaio e para uma chamada que encontrou já presente tudo o que teria anexado — uma publicação executada de novo sobre uma versão que já está completa, ou um lote de assinatura em que cada referência já tinha uma assinatura que verifica. Uma execução de ensaio continua a indicar o destino que teria endereçado. Mostre-o antes de agir com base no resultado.
Registar ou remover um registo escreve, por predefinição, a configuração partilhada por todos os espaços de trabalho da máquina. Um registo e as identidades em que confia nele são normalmente os mesmos onde quer que trabalhe, por isso é aí que a entrada vai, a menos que o pedido envie workspace: true. Vale a pena dizer claramente a consequência: aggrega/registryAdd e aggrega/registryRemove alteram aquilo através do qual todos os projetos dessa máquina resolvem, incluindo projetos que ninguém nesta sessão indicou. Ambas as respostas contêm scope, com o configFile que foi escrito e machineWide, que diz se é o partilhado. A remoção é a mais delicada das duas, porque voltar a adicionar não é o mesmo ato — a política de confiança que estava fixada desapareceu, e uma inscrição posterior fixa o que o registo anunciar nessa altura.
Semear uma configuração escreve esse mesmo ficheiro partilhado por predefinição, e pela mesma razão. aggrega/configInit regista um registo e a sua política de confiança, que é uma ferramenta de toda a máquina, pelo que sem substituição escreve a configuração através da qual todos os projetos da máquina resolvem — e acede a esse registo uma vez para ler a política que anuncia. A sua resposta contém o mesmo par scope que os dois métodos de registo contêm. Difere deles num aspeto em que vale a pena confiar: recusa em vez de sobrescrever um ficheiro de configuração existente, pelo que não pode substituir uma configuração com que alguém está a trabalhar a menos que o pedido envie force. Congelar é o caso oposto: aggrega/configCapture não aceita nenhuma substituição, escreve sempre o ficheiro de configuração do próprio projeto e não acede a nenhum registo, pelo que nada do que faz é visível para outro projeto. Consulte O que uma escrita de configuração deixa para trás.
🔴 Adicionar ou remover um plugin de extensão de comando escreve esse mesmo ficheiro partilhado por predefinição, e este é o que deve ler com atenção. aggrega/pluginAdd e aggrega/pluginRemove aceitam um type, e o tipo decide para onde vai a escrita sem substituição enviada. Uma entrada provider, governance, linter ou importer molda a compilação de um projeto, pelo que vai para a configuração desse projeto. Uma entrada cli é uma ferramenta de toda a máquina, pelo que uma adição do tipo cli que não indique nem global nem workspace regista o comando no ficheiro de configuração global através do qual todos os espaços de trabalho desta máquina resolvem — o comando passa a ser um comando aggrega de nível superior para todos os projetos dessa máquina, incluindo projetos que ninguém nesta sessão indicou, e desfazê-lo é uma remoção separada e não uma anulação. Envie workspace: true para o manter local. Ambas as respostas contêm scope, com o configFile que foi escrito e machineWide, que diz se é o partilhado, derivado do ficheiro para o qual a escrita resolveu. Uma adição acede também ao registo em que pesquisou, pelo que está em ambos os eixos ao mesmo tempo. Consulte O que uma alteração de plugin lhe diz.
Os outros dois pedidos de plugin escrevem apenas dentro do espaço de trabalho. aggrega/pluginSync escreve o ficheiro de entidade Plugin que o pedido indica, e aggrega/pluginGenCatalog escreve as entidades geradas sob o outputDir que o pedido indica — ambos dentro do espaço de trabalho que o pedido indicou, ambos recusando um destino absoluto ou que resolva para fora dele, e nenhum visível para outro projeto. aggrega/pluginGenCatalog lê o seu módulo e a sua sobreposição de onde quer que os tenha selecionado, o que não alarga o sítio onde escreve: os dois são resolvidos por regras diferentes, pelo que uma geração pode ler um módulo que compilou em qualquer sítio enquanto as entidades que produz continuam a ficar dentro do espaço de trabalho. aggrega/pluginGenCatalog com dryRun não escreve absolutamente nada e devolve o conteúdo em vez disso.
Fixar uma entidade escreve também apenas dentro do espaço de trabalho, e acede aos anfitriões que as suas origens indicam. aggrega/pin escreve o entity.lock ao lado da entidade que o pedido indica, que é um caminho dentro do espaço de trabalho, e preenche a cache de conteúdos do espaço de trabalho com as origens que obteve; nada do que escreve é visível para outro projeto. Acede ao exterior para resolver cada origem remota que a entidade indica — um repositório de charts, um anfitrião Git, um URL — que é o mesmo alcance que aggrega/resolveDependencies tem para as origens que uma Release consome. aggrega/resolveDependencies e aggrega/publishEntity com pinSources executam este mesmo passo, pelo que cada um deles escreve também ao lado das entidades que fixa; uma publicação que fixa acede assim tanto ao espaço de trabalho como ao registo. Uma publicação que não fixa não escreve nada ao lado da entidade, e mesmo assim acede a esses anfitriões: comparar o lock com o que o passo registaria significa obter por completo cada origem remota que a entidade escreve.
A instalação da skill do assistente fica dentro do espaço de trabalho, a menos que o pedido envie global. aggrega/skillsInstall escreve a pasta de skills de projeto de cada assistente indicado dentro do espaço de trabalho que o pedido indicou, e nada do que aí escreve é visível para outro projeto; o scope da sua resposta contém machineWide false. Com global: true, escreve antes a pasta por utilizador de cada assistente sob o diretório pessoal, que esse assistente lê em todos os projetos da máquina, e machineWide é true. Em qualquer dos casos, não alcança nenhum registo nem nenhuma rede.
Remover uma credencial guardada vai mais longe do que qualquer outra coisa aqui que fica por esta máquina. aggrega/logout altera o armazenamento de credenciais, e esse armazenamento é partilhado não só por todos os projetos da máquina mas por todas as outras ferramentas que se autenticam nos mesmos registos — pelo que uma credencial removida através de uma sessão desaparece para todas elas, e aggrega/registryList reportá-la-á ausente também em todos os outros espaços de trabalho. A sua resposta contém scope com machineWide, que é sempre verdadeiro: este armazenamento não tem nenhuma forma com âmbito de espaço de trabalho para a qual resolver, pelo que não há substituição a enviar nem nada que um pedido possa escolher. scope deliberadamente não indica nenhum ficheiro, ao contrário das escritas de configuração acima. O armazenamento delega no auxiliar de credenciais ou no porta-chaves do SO que a máquina tenha configurado, pelo que a remoção é frequentemente servida por algo que nem sequer é um ficheiro, e indicar um caminho apontar-lhe-ia uma localização em que a remoção não tocou necessariamente.
A remoção não é o inverso da autenticação, e um cliente não a deve oferecer como tal. Esta superfície remove uma credencial e não adquire nenhuma: recuperar uma credencial significa autenticar-se de novo com aggrega login num terminal, porque guardar uma exige um segredo escrito por uma pessoa e ninguém está a ver este fluxo. Assim, um «terminar sessão» que um cliente ofereça é, a partir daqui, de sentido único. O que separa as duas é se a operação tem de obter algo de quem a está a conduzir — uma remoção leva o seu único valor no pedido, enquanto adquirir uma credencial não — e não se há uma pessoa envolvida, uma vez que uma pessoa escolheu ambas.
Recuperar espaço de conteúdo da cache também vai além do espaço de trabalho. Os armazenamentos de módulos compilados e de descrições de plugins são partilhados por todos os projetos da máquina, pelo que aggrega/cachePrune, aggrega/cacheEvict e aggrega/cacheClear podem remover conteúdo de que outro projeto depende. Cada remoção contém o reach da classe de onde veio, e cada resposta contém scope.machineWideClasses. aggrega/cacheStatus contém o mesmo alcance em cada classe mesmo não alterando nada, porque um cliente que decide se deve recuperar espaço precisa dele antes de agir.
Atualizar o índice de pesquisa é o contrário. aggrega/registryUpdate acede a todos os registos configurados, e o que escreve fica sob o diretório de cache configurado do próprio espaço de trabalho — pelo que não altera nada através do qual outro projeto resolva. indexRoot na resposta indica esse diretório.
Uma atualização parcial responde em vez de falhar. Um pedido que indique um registo cuja atualização falhou é um erro, porque não há resposta a dar. Um pedido que atualize todos os registos configurados tem sucesso mesmo quando alguns deles, ou todos, falharam: os atualizados foram indexados e escritos, failed indica os restantes, e cada anfitrião contém o seu próprio erro. Leia failed em vez da presença de um erro.
Se um registo pôde ser alcançado é uma chave, não uma leitura da mensagem. Um anfitrião que falhou contém unreachable: true quando o registo nunca foi alcançado — o seu nome não resolveu, uma conexão a ele foi recusada ou não pôde ser aberta, ou não foi possível estabelecer uma conexão segura a ele — e a recusa de um pedido que indique um registo contém a mesma chave no seu data. Um registo que foi alcançado e falhou, com uma listagem que se repetiu ou um estado de erro, não contém nenhuma das duas, e o seu error, ou a mensagem da recusa, diz o que respondeu. A chave é lida da própria falha, pelo que não depende de como o resolvedor desta máquina formula uma falha, e só é definida quando a falha mostra que o registo nunca foi alcançado: uma falha que não mostra nada num sentido ou noutro, como um limite de tempo que se esgotou sem indicação do passo que interrompeu, é reportada sem ela. Indique um registo como não alcançado com base na chave, e mostre o erro como motivo.
A linha de comandos reporta esse mesmo percurso como uma saída diferente de zero, e o tipo de leitor que é decide o que essa saída vale. Para uma pessoa num terminal não é o relato completo: aggrega registry update imprime quantos dos registos selecionados indexou, o que cada um encontrou, quais não indexou e onde o índice foi escrito — pelo que o resumo diz o que aconteceu e o estado de saída diz apenas se tudo correu bem. Para um script é o relato completo, porque esse comando não oferece nenhum modo de saída estruturada, pelo que o seu estado de saída é o único veredicto legível por máquina disponível. É por isso que as duas superfícies respondem de forma diferente ao mesmo percurso parcial e ambas estão certas: esta entrega a quem chama de forma estruturada failed e tem sucesso, enquanto a linha de comandos tem um bit para gastar e gasta-o em «algum registo ficou de fora».
Acompanhar uma operação longa
A maioria dos pedidos aqui responde a partir do que já está no disco e responde de imediato. Alguns fazem trabalho real primeiro — resolver as dependências de uma Release, fixar as suas entradas externas, publicar, assinar, retirar — e quem chama espera. Esses reportam o que estão a fazer enquanto o fazem, e é uma opção por pedido.
Optar exige dois passos, por esta ordem.
- Declare a capacidade no handshake e espere pela resposta. Envie
capabilities.window.workDoneProgress: trueemaggrega/initialize. Não envie mais nada até essa resposta ter chegado: os pedidos são atendidos em simultâneo, pelo que um pedido escrito antes de o handshake responder pode estar a ser executado ao lado do handshake que devia negociar por ele. Todos os clientes já devem essa ordenação ao protocolo; esta é mais uma coisa que depende dela. - Coloque um token nos parâmetros do pedido. Acrescente
workDoneTokenaos parâmetros do pedido sobre o qual quer relatórios. O valor é da sua escolha — uma cadeia ou um número — e é o que liga as notificações a essa chamada. Gere um novo por chamada.
A notificação. Cada uma é $/progress com params.token definido como o seu token e params.value a conter um payload:
value.kind | contém | quando |
|---|---|---|
begin | title — o que está a acontecer, numa frase que pode colocar diante de um leitor | uma vez, quando o trabalho começa |
report | message — uma linha do relato da própria operação sobre si | qualquer número de vezes, à medida que a operação as escreve |
end | nada além do tipo | uma vez, quando o trabalho termina |
Correlacione pelo token, nunca pelo id do pedido. Uma notificação não contém nenhum id — não é resposta a nada — e o token é a única coisa nela que aponta de volta para a sua chamada. Isso é deliberado: em muitos clientes o id do pedido pertence ao transporte e nunca chega ao código que fez a chamada, enquanto o token é um valor que esse código já tem.
Um report contém o próprio texto do compilador. A mensagem é uma linha que a operação escreveu enquanto trabalhava, transmitida com o espaço em branco à volta removido e nada mais alterado — não reformulada, não resumida, não recomposta — e uma linha que a operação escreveu em branco é descartada em vez de reportada como mensagem vazia. Assim, um cliente mostra o que lhe é dado tal como está. É a mesma propriedade que os próprios diagnósticos da resposta têm: uma condição mantém uma única formulação por muitas que sejam as superfícies que a reportam.
Um passo pelo qual a operação espera também é um report. Quando a operação entra num passo pelo qual espera — ler um registo, obter um artefacto, compilar um plugin —, um report traz o nome do passo, nas palavras que a linha de comandos mostra ao lado do seu indicador de atividade para o mesmo passo. Só são reportados os passos iniciados entre o begin e o end.
Uma linha de saída é um report. Uma operação que escreve várias linhas de uma vez produz uma notificação por linha, e uma linha que a operação escreve aos bocados é reportada quando está completa — pelo que uma mensagem nunca é meia frase.
Não há fração nem percentagem, e isso não é uma omissão à espera de trabalho. As operações que reportam aqui percorrem um conjunto cujo tamanho não é conhecido quando o trabalho começa — quantas referências uma resolução percorre, quantas camadas uma publicação carrega — pelo que qualquer fração seria inventada. Desenhe um indicador indeterminado e mostre a message mais recente.
As tramas chegam antes da resposta e nunca depois dela. Um begin chega assim que o trabalho começou efetivamente, pelo que um pedido recusado pelos seus parâmetros — um caminho absoluto, um campo obrigatório em falta — não produz nenhuma notificação, apenas o seu erro. O end chega antes da resposta, e se a operação teve sucesso está na resposta em vez de ser repetido no end.
Parar o trabalho é uma notificação separada. Envie $/cancelRequest com o id com que enviou o pedido. O token não tem nenhum papel no cancelamento, e cancelar não suprime as tramas já enviadas.
Que pedidos reportam, e o que esperar dos restantes
Reportam exatamente estes: aggrega/resolveDependencies, aggrega/pin, aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts, aggrega/deprecateArtifact.
Duas coisas são verdade para cada um deles, e ambas são a razão por que está na lista: acede a um registo ou a um URL remoto em seu nome, pelo que quanto tempo demora é definido por algo fora da máquina; e já escreve o seu próprio relato de si à medida que avança — o relato que uma pessoa a observar um terminal lê. Assim, reportar entrega-lhe esse mesmo relato e não um segundo composto para o protocolo, e nada no que a operação faz teve de mudar para o produzir.
Todos os outros pedidos aceitam um token e não enviam nada. Enviar um é inofensivo e não um erro: é aceite, não chega nenhuma notificação, e a resposta é exatamente a resposta que teria obtido sem ele. Assim, um cliente pode anexar um token ao que quiser e simplesmente não desenhar nada quando nada chega.
🔴 Não interprete o silêncio como «este é instantâneo». A maioria dos restantes responde de facto a partir do que já está no disco — uma validação, um hover, uma completação, um grafo, uma listagem da cache, uma leitura de configuração — mas nem todos: atualizar um índice de registos, adicionar um plugin, uma verificação de pré-publicação e a primeira expansão de um código numa máquina que não contém documentação que o espaço de trabalho possa ler acedem todos a um registo, e compilar uma Release é trabalho real. Esses demoram o que demoram e hoje não reportam nada. Mostre um indicador indeterminado para qualquer pedido por que esteja preparado para esperar, e trate as notificações como detalhe que obtém quando está disponível e não como aquilo que lhe diz que há trabalho em curso.
Duas recusas
Ambas são erros invalid-params e ambas indicam o que fazer, porque um token que silenciosamente não fizesse nada deixá-lo-ia à espera de um fluxo que nunca viria.
- Um token de uma sessão que não declarou nenhuma capacidade
window.workDoneProgressé recusado, indicando a capacidade a declarar. Declare-a no handshake, ou deixe o token de fora. - Um token que não seja nem uma cadeia nem um número é recusado, indicando as duas formas. Um token ausente, e um
nullexplícito, não são recusas — ambos significam que não pediu nenhum relatório.
Consciência do lockfile
O daemon verifica um lockfile quanto a desvio em cada aggrega/irGraph, em relação à Release que esse pedido indicou, apresentando o desvio como aviso não bloqueante. O aviso indica o comando que reescreve esse lockfile com a Release nele, escrito como o pedido o enviou — aggrega pull --release seguido da release que enviou, que é como é escrito num terminal na raiz do espaço de trabalho. aggrega/irGraph exige que exista um lockfile. Não há verificação separada no arranque: um pedido diz a que Release se refere, pelo que o veredicto é calculado para essa Release quando é pedido e não uma vez para uma Release escolhida antecipadamente.
Um aviso de desvio desaparece quando o seu lockfile desaparece. O aviso é publicado no lockfile em relação ao qual foi levantado, e um lockfile que já não existe não tem fixações que possam ter divergido — o comando que o aviso indica escreveria um ficheiro novo em vez de reparar o antigo. Por isso, todos os pedidos que encontram o lockfile em falta retiram o aviso antes de recusarem com o erro de lockfile ausente: aggrega/irGraph, aggrega/releaseClosure, aggrega/build, aggrega/buildPreview, aggrega/attachCandidates e aggrega/attachmentContainer quando perguntam sobre um nó do grafo, e aggrega/connectionAtPosition. A retirada chega como uma notificação aggrega/publishDiagnostics para o lockfile com uma lista vazia, antes da recusa. Vem de qualquer um desses pedidos que tome conhecimento da eliminação primeiro, pelo que um cliente que reporte a eliminação e depois pergunte qualquer coisa sobre essa Release vê o aviso limpo sem pedir especificamente o grafo. Um lockfile que ainda existe e ainda diverge mantém o seu aviso em todos esses pedidos. aggrega/invalidate que indique o lockfile descarta o que o daemon tem para ele mas não envia nada; o pedido que se segue é o que informa o cliente. E um lockfile que o daemon nem sequer consegue examinar — um cujo diretório não pode ler, por exemplo — não retira nada, porque pode ainda existir e o aviso pode ainda ser verdadeiro.
aggrega/build e aggrega/buildPreview também exigem um, e sujeitam a Release a ele em vez de avisarem — renderizam sob a postura de uma superfície que emite um artefacto, pelo que um lockfile que já não corresponde àquilo para que a Release resolve os faz parar onde apenas avisaria uma inspeção. Uma Release sem lockfile é recusada com o erro de lockfile ausente. A exceção é uma compilação cujo campo autoPull lhe pede que resolva primeiro as dependências: essa compilação escreve o lockfile e depois renderiza com base no que escreveu, e um lockfile produzido dessa forma não é verificado quanto a desvio uma segunda vez, porque a resolução que o escreveu executou a mesma verificação sobre ele antes de o escrever e não escreve nenhum lockfile que essa verificação recuse.
Um lockfile que existe mas não regista nenhum digest para um plugin não impede o grafo — um lockfile ausente impede. São duas condições e só a segunda recusa. aggrega/irGraph não sujeita os bytes para os quais resolve aos seus digests registados: uma fixação que não consegue verificar é reportada em vez de recusada, e o grafo é desenhado com a constatação no painel Problemas, uma vez que um editor que se recusa a desenhar o grafo deixa o leitor sem nada, enquanto um relatório lhe deixa algo sobre que agir. Noutros sítios o plugin também é executado, com um aviso a dizer que nada verificou os seus bytes. O que aggrega/irGraph recusa é o lockfile em falta: para antes de resolver o que quer que seja e responde com o erro de lockfile ausente, indicando o lockfile que procurou e a Release, para que um cliente possa oferecer diretamente aggrega pull --release <release> — ou enviar aggrega/resolveDependencies para essa Release e escrever o lockfile sem sair da sessão. Manter as duas separadas importa, porque um grafo desenhado é uma imagem sobre a qual um leitor depois raciocina, e um construído a partir de bytes que nada verificou é desenhado exatamente como um que foi verificado, com a constatação num sítio para onde o leitor não está a olhar. Assim, um grafo não é um veredicto sobre os bytes por trás dele — aggrega/build e aggrega/buildPreview são as superfícies que sujeitam uma Release aos seus digests registados, parando onde a inspeção reporta.
aggrega/validate, quando um pedido indica uma Release, lê o lockfile dessa Release apenas para as suas fixações e os seus avisos de descontinuação — e não lê nenhum para uma entidade de catálogo que verifica como entidade única, tal como a linha de comandos não lê nenhum. Não sujeita os plugins que executa aos digests registados, e não reconstrói o conjunto de anexos de plugins de transformação a partir do lockfile — valida com a configuração do espaço de trabalho tal como está à sua frente, que é o que um editor tem de fazer enquanto edita essa configuração. aggrega validate e aggrega build fazem ambos, e continuam a ser as superfícies de referência para um veredicto sobre um espaço de trabalho submetido.
Os seus avisos de descontinuação abrangem os dois locais onde uma retirada é registada. Um marcador numa referência fixada está no lockfile; um marcador num plugin anexado num papel que devolve um veredicto de aceitação ou rejeição — um anexo plugins.governance em ir-verdict ou render-verdict, ou um anexo plugins.linter — está no registo de confiança dos plugins ao lado dele, pelo que a validação lê ambos e indica cada referência retirada e cada plugin retirado como um aviso no início do Aggregate, nas palavras que aggrega build imprime. Um aviso de descontinuação não altera nenhum veredicto. Um registo de confiança que existe e não pode ser lido é reportado como erro no lugar da validação, em vez de ser lido como um que não regista nada. aggrega/releaseClosure reporta o mesmo conjunto no seu deprecations.
Onde está o lockfile de uma Release
Todas as respostas que indicam uma Release indicam também o seu lockfile, para que um cliente nunca tenha de deduzir o caminho. aggrega/activeRelease contém-no como lockfile ao lado de release, aggrega/releaseCandidates como o mapa lockfiles ao lado de releases, e o erro de lockfile ausente como lockfile no seu data. Cada um é o ficheiro que aggrega pull --release <release> escreve e aggrega build lê, e o ficheiro que cada pedido acima verifica — pelo que um cliente que observe o lockfile de uma Release, para dar conta de que é escrito, reescrito ou eliminado, observa o ficheiro a que o daemon se refere. O lockfile fica ao lado da sua Release e recebe o nome da Release com uma extensão .yaml ou .yml substituída por .lock; uma Release com qualquer outra extensão mantém o seu nome completo, pelo que o lockfile de release.rel é release.rel.lock. Leia o caminho da resposta em vez de o compor a partir desta descrição, e os dois não podem divergir.
As referências externas que uma renderização pede
Uma renderização pode pedir conteúdo de um URL remoto — o esquema de valores de um chart com uma referência remota, por exemplo. As entradas externas ficam congeladas em todas as renderizações que este daemon efetua em resposta a um pedido que apenas pediu para ser informado de algo. Uma referência que o lockfile da Release fixa é servida a partir do armazenamento endereçado por conteúdo, que é uma leitura de conteúdo já no disco e não uma obtenção, e é verificada com o que o lockfile regista antes de os seus bytes serem servidos — pelo que uma renderização aqui vê o que uma compilação vê, e levanta os avisos que uma compilação levanta. Uma referência que o lockfile não fixa é declinada em vez de obtida: adquiri-la acederia a uma rede e escreveria um blob no armazenamento, e uma sessão não faz nenhuma das duas coisas num pedido que apenas pediu para ser informado de algo. Essa é a regra de Aceder a um registo e escrever lida do lado da renderização, e verifica-se qualquer que seja a forma como tal renderização foi alcançada.
O pedido que existe para fixar é a exceção, e é a mesma exceção que a regra do registo já contém. aggrega/resolveDependencies é encarregado de adquirir, pelo que a renderização que efetua para descobrir que referências esta Release consome acede à rede e escreve o que fixa — que é o que torna o seu resultado um lockfile e não um relatório. Nenhuma renderização que um pedido de grafo ou de compilação efetua por si faz nada disso.
Uma compilação a que se pede que resolva primeiro é respondida a partir dessa mesma renderização, e é por isso que renderiza a Release uma vez. A resolução já renderizou aquilo de que trata a compilação, com as fixações que acabou de escrever e sob as barreiras que uma compilação executa, pelo que a compilação apresenta essa renderização em vez de efetuar uma segunda — e a aquisição continua a pertencer à resolução e não à compilação. Só uma renderização que terminou é usada dessa forma: quando uma resolução fixou as suas dependências mas não conseguiu terminar a descoberta das referências externas, a compilação renderiza por si com as fixações que ficaram, e uma referência não fixada é declinada e reportada aí exatamente como numa compilação que não resolveu nada.
A declinação é reportada em vez de absorvida, porque nada num resultado diz que referência lhe faltou. Com os fornecedores que este binário contém, o fornecedor que pediu a referência devolve a recusa, pelo que uma renderização que alcançou uma referência declinada não termina. Cada referência declinada chega assim como entrada própria na camada aggrega-build, indicando a referência e o comando que a fixa: aggrega pull --release <release>, ou aggrega/resolveDependencies para o mesmo trabalho sem sair da sessão. As entradas são consultivas e não uma recusa — o grafo continua a ser devolvido, com o mesmo estatuto que o aviso de desvio acima — e são atribuídas ao Aggregate no início do ficheiro, porque uma referência que uma renderização pediu não indica nenhuma chave que um autor tenha escrito. Viajam na mesma publicação que os próprios avisos da renderização, que substitui essa camada por inteiro, pelo que uma referência que venha a fixar deixa de ser reportada sem que nada tenha de a limpar. Uma renderização totalmente fixada não diz nada sobre isto. Consulte O que contém uma entrada de diagnóstico para a forma de cada entrada.
Em aggrega/irGraph isto depende de a fase de renderização ser de todo executada. O pedido de grafo salta a renderização a menos que --build-on-inspect, ou a chave serve.build_on_inspect que este substitui, a ative; com o seletor desligado nada pede uma referência externa e não há nada a declinar. Ativá-lo é o que traz tanto os próprios avisos da renderização como estes para uma sessão de editor.
Onde uma sessão difere do mesmo congelamento na linha de comandos. aggrega build congela as entradas externas também numa execução de ensaio, e uma referência não fixada comporta-se da mesma forma em ambas as superfícies: é reportada como constatação que indica a referência, e a renderização então para, porque o fornecedor que a pediu devolve a recusa. O que difere é a nova obtenção. Na linha de comandos, uma referência fixada cuja cópia armazenada desapareceu é obtida de novo pelo seu digest registado; a renderização que responde a um pedido de grafo ou de compilação não volta a obter nada, porque essa renderização não acede à rede, pelo que não pode ir buscar de novo uma referência fixada que o armazenamento já não contém — e tal referência não está entre as declinações descritas acima, que indicam o que o lockfile não fixa. Pedir a uma sessão que fixe é o que a recupera: os pedidos indicados acima acedem à rede e repõem os bytes em falta. Consulte aggrega pull para saber o que a fixação obtém e regista.
O que uma execução recusada ainda indica
Um pedido que recusa responde com um envelope de erro, e as constatações que a execução já tinha feito não viajam dentro desse envelope — o envelope não transporta qualquer corpo de resultado. Chegam ao cliente da mesma forma que numa execução que terminou: como uma publicação de diagnósticos na camada aggrega-build, descrita em O que uma entrada de diagnóstico transporta. Assim, um cliente que trata uma recusa lê o envelope para saber o que alterar e a sua superfície de problemas para saber o que a execução encontrou, e nenhum substitui o outro. Uma recusa levantada durante a renderização é a única recusa que é também uma constatação sobre o que um autor escreveu, pelo que chega a ambos, como descreve a secção seguinte.
Essa publicação acontece quer a execução tenha chegado ao fim, quer não. Uma execução que para a meio encontrou ainda assim tudo o que estava antes do ponto em que parou, e um leitor que perdesse essas constatações teria de executar novamente para as ver — por isso, os avisos são publicados a partir daquilo a que a execução chegou, e a recusa é devolvida depois. É o mesmo conjunto com a mesma fidelidade, posicionado nas mesmas chaves de autoria: uma recusa não despromove uma constatação a uma frase. As referências externas recusadas viajam nessa mesma publicação, pela mesma razão e pela mesma via.
O que a limita é até onde a execução chegou, não o que a camada pode transportar. Uma recusa de uma das verificações que correm antes de o compilador arrancar — não foi possível resolver o fecho da Release, o Manifest mapeia um tipo para uma receita que não o implementa, o lockfile já não corresponde àquilo para que a Release resolve, uma entrada fixada na cache já não corresponde ao digest registado para ela e nenhum diretório de catálogo contém os bytes fixados — não tem avisos a publicar, porque ainda nenhum tinha sido levantado. A camada não transporta então nada, em vez de algo desatualizado; e uma execução que não chegou a nomear um documento não publica rigorosamente nada, deixando o que já está na sua superfície de problemas exatamente como estava, em vez de limpar entradas sobre as quais nada apurou.
Uma recusa levantada durante a renderização
Uma Release que o compilador recusa enquanto a renderiza — um Workload que nomeia um slot que o seu Component não declara, uma asserção que falha, um template que não pode ser avaliado, uma realização aquém do que tem de fornecer — é reportada onde aponta e nas palavras do compilador, em todos os pedidos que a renderizam: aggrega/build, aggrega/buildPreview e aggrega/irGraph com a fase de renderização ativada. A resposta é um envelope de erro com o código -32603, cuja message é a recusa com todas as causas por baixo dela, nas palavras que a linha de comandos imprime para a mesma compilação: o nó a ser renderizado, depois o que nele recusou, cada causa a seguir àquela que explica — precedida, quando a recusa nomeia uma condição registada, pelo código curto dessa condição, como acontece com todas as recusas que nomeiam uma. O seu data nomeia o documento para onde a recusa aponta como file, e a extensão da chave nesse documento como line, column, end_line e end_column, ao lado do code e do shortCode da condição; uma recusa que não nomeia nenhuma chave, ou uma chave que o documento não contém, transporta apenas file, e uma que não aponta para nenhum documento nomeia o Aggregate da Release.
A mesma recusa é publicada na camada aggrega-build, nesse documento, nessa chave, como uma entrada de gravidade error que transporta o keyPath da própria recusa e a message do envelope sem o código curto à frente, e — quando a recusa nomeia uma condição registada — o code, o shortCode e o codeDescription dessa condição, viajando aí o código curto no seu próprio campo. Viaja na única publicação que transporta os avisos que a execução levantou antes de parar, pelo que substitui a camada tal como eles: a execução seguinte da Release que renderiza publica a camada sem ela, e o documento onde estava é publicado vazio, o que a remove da sua superfície de problemas.
O local para onde uma recusa aponta é o que a própria recusa nomeia, e nada mais fino. As verificações de um Workload julgam o documento que o seu template produziu, e um template pode escrever linhas que nenhum autor escreveu — um ciclo, uma condição, um texto importado de um ficheiro ou de uma biblioteca —, pelo que uma linha do Workload renderizado não corresponde a uma linha da Recipe. Uma recusa sobre um Workload é, portanto, colocada na chave workload da Recipe, e os caminhos que nomeia dentro do documento renderizado ficam na sua mensagem. Uma asserção que falha é colocada na sua própria chave em assertions, na Recipe ou na FeatureRecipe que a declara; uma asserção que um Component ou uma Feature declara é levantada antes de haver qualquer documento para nomear, e é colocada na chave kind: do Aggregate. Uma recusa de um passo que nomeia um documento mas nenhuma chave é colocada na chave kind: desse documento.
Uma recusa que junta várias constatações é publicada constatação a constatação. A composição do grafo a partir do qual a renderização trabalha recusa com todas as violações que encontrou numa só recusa — uma entrada que nomeia um destino ao qual nada responde, duas ligações de um componente com o mesmo alias — e a linha de comandos imprime cada uma como um diagnóstico próprio, sob o seu próprio cabeçalho. Aqui, cada uma é uma entrada própria na camada aggrega-build, no documento e na chave que essa constatação nomeia — a Release, onde foi a Release a escrevê-la, o Aggregate, onde foi o Aggregate — nas suas próprias palavras e com os seus próprios códigos. A message da resposta transporta todas as constatações, e o seu data nomeia para onde aponta a primeira.
Um valor que um autor declarou sensível é ocultado aqui exatamente como a linha de comandos o oculta. O texto da recusa é o texto que o compilador levantou, nada nesta superfície o reformula, e o compilador oculta um valor declarado no ponto onde a recusa é levantada — <redacted> no seu lugar —, pelo que esta resposta, esta entrada e o terminal o transportam com as mesmas palavras; o que uma recusa diz sobre um valor declarado indica como, e que recusas ficam fora disso.
Uma recusa de uma barreira que corre antes da renderização não é isto. As verificações enumeradas acima respondem como descreve O que uma execução recusada ainda lhe diz. Uma asserção que um Component ou uma Feature declara, e uma recusa sobre o grafo composto, ficam entre as duas: cada uma é levantada antes da renderização, por todos os pedidos que resolvem o grafo de uma Release, pelo que aggrega/irGraph a responde e publica como acima também com a fase de renderização desativada; aggrega/releaseClosure, aggrega/attachCandidates e aggrega/attachmentContainer, quando questionados sobre um nó do grafo, e aggrega/connectionAtPosition respondem-lhe com o mesmo envelope e não publicam nada, porque não possuem qualquer superfície de problemas.
Códigos de erro
As respostas usam os códigos de erro padrão do JSON-RPC, mais um intervalo ao nível da aplicação na faixa 1xxx. Um cliente de editor pode ramificar com base no código sem analisar a mensagem.
1001file-not-validated — o daemon não tem nada para o ficheiro, tal como está agora, a partir do qual o pedido possa responder: nenhuma análise dele ou, paraaggrega/diagnostics, nenhuma análise dele ou nada guardado para o ficheiro que seja a resposta de uma validação para o texto que o daemon tem agora. Envieaggrega/validatepara ele e pergunte novamente.1003lockfile-absent — a Release que o pedido nomeou não tem lockfile, e a operação pedida precisa de um.1004entity-not-resolvable — o nome não correspondeu a nenhuma entidade em nenhum nível do catálogo, nem na Release que o pedido nomeou; ou a referência de registo enviada como nome não pôde ser lida como uma entidade, e a mensagem nomeia a condição que diz porquê; ou o lockfile da Release é uma ligação que conduz para fora do espaço de trabalho, o que é recusado antes de qualquer coisa o ler, comdataa nomear o lockfile e a Release e com a mensagem a abrir com o código curto da condição,E0321— consulte o limite do espaço de trabalho.1005shutting-down — o daemon está a esvaziar-se após uma notificação de encerramento e recusa novos pedidos. Não volte a tentar contra o mesmo subprocesso.1006validation-in-flight — está a decorrer uma validação do ficheiro que não terminou dentro do orçamento de tempo que o pedido em espera lhe concedeu. Pergunte novamente daqui a pouco e não envie nada.
1002 não está atribuído e está disponível para a próxima condição que precise de um código.
File-not-validated e validation-in-flight reportam estados opostos, e a ação que cada um pede também é a oposta. File-not-validated significa que o daemon não tem nada para o ficheiro, tal como está agora, a partir do qual o pedido possa responder — nenhuma análise dele ou, para aggrega/diagnostics, nenhuma análise dele ou nada guardado para o ficheiro que seja a resposta de uma validação para o texto que o daemon tem agora: envie aggrega/validate e pergunte novamente. Uma validação cancelada a meio deixa um ficheiro nessa situação, porque não guarda nada e o que uma validação anterior encontrou sobre um texto diferente não é uma resposta para o texto que o daemon tem agora; uma resposta anterior continua válida enquanto o texto for aquele que verificou. As constatações que o daemon envia sobre um ficheiro que ele próprio leu do disco — um lockfile que divergiu, uma Release que não carrega — não são uma validação do texto que tem, pelo que também não respondem a este pedido. Duas validações de textos diferentes enviadas com pouco intervalo também o podem deixar nessa situação, quando aquela cujo texto o daemon manteve terminou primeiro: o pedido é recusado embora esse texto tenha sido verificado, e validar novamente responde-lhe. É formulado em termos da análise e não do ficheiro porque um buffer que nenhum analisador lerá está exatamente nessa posição — a validação correu e reportou o que encontrou, e continua a não haver nenhuma análise a partir da qual responder. Validation-in-flight significa que está a decorrer uma validação dele que não terminou dentro do orçamento que o pedido em espera lhe concedeu: pergunte novamente daqui a pouco e não envie nada, porque o estado de que precisa já está a caminho e uma segunda validação só acrescentaria trabalho. Ler os dois como uma só condição leva um cliente a enviar uma validação precisamente no caso em que enviá-la é a jogada errada. As duas faixas significam coisas diferentes para um cliente: um código 1xxx nomeia um estado do espaço de trabalho sobre o qual o utilizador pode agir — validar o ficheiro, gerar o lockfile —, enquanto um código padrão como invalid-params nomeia um pedido malformado, que é o cliente a corrigir e não o utilizador. Um valor release presente mas malformado — absoluto, ou que resolve para fora da raiz do espaço de trabalho — cai na segunda faixa: não é o espaço de trabalho que está num estado que o utilizador tenha de reparar, é o pedido. Omitir release não cai em nenhuma das faixas, porque não é de todo um erro; seleciona a mais restrita das duas respostas descritas em Validação em tempo real.
Um erro pode transportar um objeto data, e cada chave nele nomeia uma coisa e apenas essa coisa. file é o documento de origem a que a falha diz respeito — o documento a ser validado, a Release cujo carregamento falhou, o documento do espaço de trabalho que declara um nome que nada resolveu, ou o documento para onde aponta uma recusa levantada durante a renderização — e é nele que quaisquer line e column que o acompanhem localizam uma posição. Esses dois são, eles próprios, opcionais: uma falha sobre um documento inteiro transporta apenas file. lockfile é um lockfile. release é a Release a que o erro diz respeito, escrita da forma como o pedido a nomeou, para que um cliente possa compor aggrega pull --release <release> sem a extrair de volta da mensagem. unreachable indica que o registo que um pedido recusado nomeou não pôde ser contactado: uma atualização de índice recusada que nomeia um registo transporta-o, lido da própria falha, e um registo que respondeu deixa-o ausente. Todas as chaves são opcionais e só estão presentes quando o daemon tem esse valor em mãos; nenhuma substitui outra, pelo que aquilo para que uma chave aponta nunca depende do código ao lado dela.
code e shortCode em data nomeiam a condição que uma recusa reporta, em todas as recusas que reportam uma condição registada, seja qual for o seu código numérico: o código descritivo com base no qual um programa ramifica e o código curto que uma pessoa cita, os mesmos dois identificadores, com os mesmos nomes, que uma entrada de diagnóstico transporta para a mesma condição, e enumerados na tabela de todas as condições. Ramifique com base em code. O código numérico nomeia o estado do pedido e mantém-se o mesmo para muitas condições — uma compilação recusada porque uma ligação de catálogo conduz para fora e uma compilação recusada porque um nome não resolve para nada são ambas 1004 — e a mensagem é prosa que pode ser reformulada, pelo que nenhum deles distingue uma condição de outra. Invalid-params é um desses códigos partilhados: um pedido que nomeia um espaço de trabalho cujo ficheiro de configuração conduz para fora dele também o obtém, e aí read-leads-out-of-workspace indica que a falha está na estrutura do espaço de trabalho, que uma pessoa repara, e não no pedido. Uma recusa que não reporta nenhuma condição registada não transporta nenhuma das chaves, e as duas estão presentes em conjunto ou não estão de todo. A mensagem de uma recusa que nomeia uma condição abre com o seu código curto, E0321: …, uma vez, que é a forma que uma pessoa que a lê encontra em todas essas recusas; uma recusa cuja mensagem já abre com um cabeçalho entre parênteses retos que transporta o código — o relatório de uma linha de um documento de catálogo que o carregamento recusou — não o recebe novamente.
O relato de como decorreu a cascata de Releases do espaço de trabalho viaja na resposta de aggrega/activeRelease, no seu campo trace, e não num erro: um espaço de trabalho que não aponta para nenhuma Release é um estado normal e não um pedido falhado. É prosa de diagnóstico escrita para uma pessoa ler, não uma estrutura para analisar. Mostre-a tal como está — escreva-a num ficheiro de registo, ou num painel que o utilizador possa abrir — e não procure padrões nela, não extraia valores dela nem ramifique com base nas etiquetas que usa: a sua redação, a sua disposição e essas etiquetas acompanham a própria cascata e mudam sempre que a cascata muda. Um cliente que passa o texto adiante continua a funcionar após uma alteração dessas; um que aprendeu a sua forma deixa de funcionar com ela.
Ver também
- ../schema/other/serve-wire.md — as formas das mensagens que este protocolo troca, geradas a partir do esquema publicado: o objeto de parâmetros de cada método, cada resultado e cada carga útil de notificação, campo a campo.
- ./aggrega-build.md — o comando de compilação, cujo pipeline do compilador, barreiras e resolução de dependências
aggrega/buildtambém executa, pelo que as duas superfícies escrevem uma única árvore de saída e não duas. - ./aggrega-version.md — o comando de versão que uma extensão de editor usa para verificar a compatibilidade do daemon.
- ./aggrega-pull.md — o lockfile que a superfície de desvio do daemon lê.
- ./aggrega-lint.md — as convenções de publicação que o daemon reporta a pedido, e em cada validação assim que
serve.lint_on_validateestiver ativado.
Sinopse
aggrega serve [flags]Descrição
Run the Aggrega compiler as a long-running service. The daemonreads JSON-RPC 2.0 messages from stdin and writes responses to stdoutunder the aggrega/ method namespace. State (parsed YAML, diagnostics,resolved catalog) holds across requests so IDE clients can issue manycheap operations without re-paying per-invocation startup cost.
The daemon resolves its workspace root through the same path everyaggrega command uses: --workspace-root when set (used as-is, validatedto exist as a directory), otherwise discovery walking upward from thecurrent working directory. A directory anchors the workspace when itholds a .aggrega-config.yaml carrying a workspace: block, or — as afallback — any of .aggrega/, aggregate*.yaml, release*.yaml,manifest*.yaml.
Configuration is the cascade composition of the .aggrega-config.yamlfiles from the workspace root down to the working directory (neareroverrides farther), beneath which the global config file — the one--config names, else the one the AGGREGA_CONFIG environment variablenames, else the default location when a file is there — and thebuilt-in defaults apply.
The daemon honors the aggrega/shutdown JSON-RPC notification for acooperative cross-platform exit: the daemon completes the in-flighthandler if any, refuses new requests with code 1005, and exitscleanly within a 2-second drain budget.
Asking the process itself to stop — an interrupt from the terminal, ora termination request from a supervisor or container runtime — takesthe same path on the same terms: the first request drains the daemonand it exits cleanly, and a second ends the process at once.Flags
| Flag | Predefinição | Descrição |
|---|---|---|
--build-on-inspect | false | Executa a fase de renderização de artefactos ao inspecionar um grafo IR, para que os avisos que aggrega build levanta durante a renderização apareçam também como problemas no editor. Não acrescenta nenhuma das verificações em que uma compilação para. Nada é escrito em disco: nem artefactos renderizados, nem diretório de saída, nem lockfile. Desativado por predefinição, em conformidade com aggrega inspect, que também não levanta nenhum aviso desse tipo. Quando definido, substitui a chave de configuração serve.build_on_inspect. |