Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

aggrega serve

aggrega serve executa o Aggrega como um daemon compiler-as-service de longa duração para integração com IDEs. Ele fala JSON-RPC 2.0 sobre stdin/stdout e mantém o estado do catalog-resolver, do parse-cache e dos diagnósticos entre as solicitações, de modo que as operações do editor recebem retorno em menos de um segundo em vez de pagar o custo completo de carregamento do catálogo a cada tecla pressionada.

O daemon normalmente é iniciado como subprocesso por uma extensão de editor, e não executado manualmente. Uma extensão do VS Code é o cliente de referência; outros editores podem se integrar falando o mesmo protocolo.

O protocolo

O protocolo de transmissão é JSON-RPC 2.0 com framing Content-Length, sob o namespace de métodos aggrega/. Ele intencionalmente não é o Language Server Protocol — o Aggrega tem operações de domínio (uma consulta ao grafo de IR, um sinal de invalidação de cache) para as quais o LSP não tem equivalente. Uma extensão de editor traduz entre as solicitações LSP do editor e esses métodos aggrega/*; valores de posição, intervalo e localização no formato do LSP são reutilizados onde se encaixam.

Dois métodos mantêm seus nomes $/ padrão do protocolo em vez de serem renomeados para o namespace aggrega/, porque ambos são questões de transporte que não têm nenhum significado para o Aggrega, e um cliente que já fala o protocolo os trata sem acrescentar nada: $/cancelRequest, que interrompe uma solicitação cuja resposta o cliente não quer mais, e $/progress, que é como o daemon informa sobre uma operação longa enquanto ela é executada. Ambos são descritos abaixo.

🔴 Toda solicitação abaixo traz workspaceRoot, o caminho absoluto do workspace sobre o qual ela age, e isso não é repetido para cada método. Três não o trazem, porque seu assunto não é um workspace: aggrega/initialize, aggrega/getSchema e aggrega/scaffoldEntity — exceto que aggrega/scaffoldEntity, ao escrever ou listar um exemplo executável, nomeia um. Consulte Toda solicitação nomeia o workspace a que se refere para saber o que recebe uma solicitação que não nomeia nenhum, e Declarar o workspace para o qual você quer receber diagnósticos para saber para onde vão os diagnósticos enviados.

Os formatos campo a campo são publicados como um schema, e a referência dos formatos de transmissão é onde lê-los. Essa página informa o objeto de parâmetros de cada método, cada resultado e cada payload de notificação — cada campo com seu tipo, se é obrigatório e o que traz — junto com três propriedades que valem para toda a superfície em vez de por método: os dois campos que toda solicitação admite além dos que seu próprio método declara, que são workspaceRoot acima e o workDoneToken de Acompanhar uma operação longa; que um objeto params com uma chave que seu método não aceita é recusado, com o conjunto aceito nomeado na recusa; e onde uma coleção ausente chega ao fio como null em vez de como uma coleção vazia. Ela é gerada a partir desse schema, portanto muda quando o contrato muda.

Esta página traz o protocolo, aquela traz os formatos, e elas foram feitas para serem lidas juntas. Aqui: o framing, para que serve cada método, até onde ele alcança, o que escreve, quais recusas gera e por quê, os códigos de erro e o que fazer em cada caso. Lá: o que colocar no fio, chave por chave. Assim, a lista abaixo nomeia cada método e diz o que significa consultá-lo, e a lista de campos da solicitação que você está montando está na referência ao lado.

Solicitações:

  • aggrega/initialize — handshake. Negocia a codificação de posições (o servidor prefere UTF-8, depois UTF-16, depois UTF-32, e usa UTF-16 por padrão), recebe o workspace que você declara para os diagnósticos enviados e informa a raiz desse workspace, a camada de configuração da qual suas configurações foram resolvidas e o marcador que a resolveu. A resposta também traz version, a versão do binário que responde: o mesmo valor que aggrega version informa para esse binário. Ela descreve o processo em execução, então, depois que o arquivo a partir do qual o daemon foi iniciado é substituído — por uma recompilação no mesmo caminho, por exemplo —, version ainda nomeia o daemon em execução, enquanto consultar o arquivo nomeia seu substituto; leia-o aqui quando a pergunta for com qual versão você está falando. workspaceRoot é opcional e declara um workspace em vez de agir sobre ele — consulte Declarar o workspace para o qual você quer receber diagnósticos. Envie capabilities.window.workDoneProgress: true para dizer que seu cliente consegue lidar com notificações de progresso; capabilities.workDoneProgress na resposta repete isso, e o campo fica ausente para um cliente que não declarou nada. Consulte Acompanhar uma operação longa.
  • aggrega/validate — valida o conteúdo de um arquivo; retorna diagnósticos. release é um caminho relativo à raiz do workspace que nomeia a Release com base na qual validar — o mesmo valor que aggrega/irGraph recebe, e o mesmo valor que aggrega build --release recebe quando executado a partir da raiz. É opcional e determina até onde a resposta alcança: nomeie uma Release e as verificações que precisam de uma são executadas com base nela — uma entidade de catálogo é verificada como entidade isolada nos termos dessa Release, e qualquer outro documento com base no fechamento de dependências dessa Release; omita-o e a resposta cobre o que se pode exigir do documento por si só, e traz checked para indicar isso. Um valor presente, mas malformado, é recusado de qualquer forma — um caminho absoluto, ou um que se resolve fora da raiz do workspace, é rejeitado em vez de resolvido. Consulte Validação ao vivo.
  • aggrega/diagnostics — retorna as constatações mantidas para um arquivo. Se uma validação desse mesmo arquivo estiver em execução quando a solicitação chegar, a resposta aguarda por ela e informa o que ela encontrou, de modo que a resposta nunca é um atestado de boa saúde para um arquivo no qual o daemon está no meio de encontrar problemas. Consulte Pedir diagnósticos enquanto uma validação está em execução.
  • aggrega/hover — conteúdo de hover para a entidade em uma posição. release é opcional e responde nos termos dessa Release — consulte Responder nos termos de uma Release.
  • aggrega/completion — candidatos de autocompletar em uma posição. Onde o cursor nomeia uma entidade por tipo — o type de um componente, o type de um vínculo de Feature, um valor extends:, o implements: de uma Recipe ou de uma FeatureRecipe —, os candidatos são os nomes desse tipo que os próprios documentos do seu workspace declaram e, para um Component ou uma Feature, também os nomes que seus catalog_dirs configurados declaram, cada um oferecido uma vez e em ordem de nome. Um workspace que obtém seus Components e Features de um catálogo recebe, portanto, essas ofertas, e não apenas o que ele mesmo escreveu. Recipes e FeatureRecipes, oferecidas no valor de um mapeamento do Manifest, vêm dos próprios documentos do workspace. Uma entidade que apenas o cache de artefatos ou um registry contém não é oferecida: responder a um autocompletar nunca baixa nada. release é opcional e responde nos termos dessa Release — consulte Responder nos termos de uma Release.
  • aggrega/resolve — resolve a entidade referenciada em uma 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 recebe um release opcional e responde nos termos dessa Release — consulte Responder nos termos de uma Release.
  • aggrega/irGraph — o grafo de IR compilado de uma Release, para introspecção no editor. release é um caminho relativo à raiz do workspace, que nomeia uma Release dentro dele — o mesmo valor que aggrega build --release recebe quando executado a partir da raiz. Qualquer outra forma é recusada com o erro padrão invalid-params, que nomeia o que enviar no lugar: um caminho absoluto, um caminho que se resolve fora da raiz do workspace — seja saindo dela como está escrito, seja por meio de um link, para o arquivo ou para um diretório no caminho — e um valor vazio são todos rejeitados em vez de resolvidos, de modo que uma solicitação nunca informa sobre um arquivo que o workspace não contém. Uma Release que a configuração do seu workspace nomeia, como build.authoring_release ou como chave de workspace.releases, pertence ao workspace onde quer que seu arquivo esteja, portanto um link dentro do workspace que leve a ela é aceito, assim como aggrega/releaseCandidates a 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 como aggrega inspect o recusa, antes que qualquer outra coisa seja lida: o erro é 1004 entity-not-resolvable, sua mensagem é o relatório que a linha de comando imprime para esse diretório, em uma linha ([CATALOG_ERROR] <directory>: catalog load: …), e nenhum grafo é traçado sobre os diretórios restantes. Um diretório que a configuração do workspace lista e que não é um diretório — nada existe ali, por exemplo — é recusado da mesma forma e no mesmo momento, 1004 entity-not-resolvable, tendo como mensagem a recusa que todo comando lhe dá, que nomeia a entrada, o arquivo de configuração e a linha que a listam e a opção (De onde as entidades locais são lidas). Um diretório de catálogo que contém um link que sai do diretório dentro do qual suas leituras devem permanecer — um documento ou diretório vinculado de outro lugar, sob um diretório de catálogo dentro do workspace ou sob um que a configuração nomeia fora dele — é recusado da mesma forma e no mesmo momento, com 1004 e a frase própria da condição nomeando o link e para onde ele leva: nada é lido por meio de um link assim, e um grafo traçado sem ele poderia resolver outra entidade de mesmo nome em seu lugar. O mesmo vale para um link que sai dos documentos ao lado da Release, onde a Release nomeia seu Aggregate ou seu Manifest por identidade. Um arquivo que a Release, seu Manifest ou uma Release que ela estende nomeia por um caminho — aggregate:, manifest:, extends: ou um $import: de parameters — e que sai do workspace, como está escrito ou por meio de um link, é recusado com a frase própria 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 arquivo sai do diretório dentro do qual deve permanecer)”), com os dados do erro situando-o na chave da Release que levou ao arquivo, e nada é lido desse arquivo; uma Release que a configuração nomeia fora do workspace fica presa da mesma forma ao diretório que a contém, portanto também é recusado um caminho, escrito por ela ou por uma Release a que sua cadeia leva, que saia desse diretório. Observe que aggrega/releaseCandidates responde com caminhos absolutos, então um cliente que alimenta uma superfície com a outra converte entre as duas. O fato de este parâmetro recusar uma grafia que os parâmetros por documento file e uri aceitam é proposital, e Quais grafias um parâmetro que você envia aceita diz o que decide isso. O grafo oculta todo valor que um autor declarou sensível, exatamente como --ir-graph o oculta na linha de comando: cada um é substituído pelo marcador que aggrega-inspect descreve em “Saída legível por máquina”, e todo o resto é transmitido como o compilador o registrou. unredacted: true pede esses valores em texto claro — a grafia do protocolo para o --unredacted da linha de comando, e a única forma de pedi-los; ausente ou false, a resposta os oculta. Tudo o que a resposta alcança passa então a trazer os valores em texto claro, portanto um cliente só os pede onde a pessoa que o usa tiver pedido.
  • aggrega/build — compila uma Release e escreve seus artefatos no diretório de saída do workspace, o mesmo diretório em que aggrega build escreve quando executado a partir da raiz do workspace. release traz o mesmo contrato descrito acima. Ele renderiza com todas as verificações ativas, de modo que uma divergência na qual um build de linha de comando 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 como aggrega build o recusa, antes que qualquer coisa seja escrita: nenhum artefato, e nenhum lockfile quando autoPull está definido. O mesmo vale para um diretório que a configuração do workspace lista e que não é um diretório, nos termos em que aggrega build o recusa (De onde as entidades locais são lidas). A recusa é a que aggrega/irGraph dá para o mesmo diretório, 1004 entity-not-resolvable com o relatório da linha de comando em uma única linha, e um link que sai das leituras de um diretório de catálogo, ou dos documentos ao lado da Release, é recusado como aggrega/irGraph o recusa, sem escrever nada. A resposta nomeia o outputDirectory em que escreveu e os files que escreveu, cada um relativo a esse diretório e ordenados, junto com quaisquer notices que a execução gerou; as constatações que trazem uma posição no documento trafegam por aggrega/publishDiagnostics em vez disso. Uma Release que recusa durante a renderização é respondida com essa recusa nas palavras do compilador, com todas as causas, e a recusa é publicada onde ela aponta — veja Uma recusa gerada durante a renderização. Quando autoPull estava definido, a resposta também traz dependencyResolution, o mesmo relatório com que aggrega/resolveDependencies responde, de modo que um cliente que preencheu as dependências como parte do build lê o que foi fixado sem perguntar de novo — e de onde a resolução deste build tirou cada referência, um fato sobre essa execução que o lockfile não registra. Cada aviso traz a class da superfície que o gerou — deprecation, catalog, catalog-lint, extends, release-composition, ou dependency-resolution para uma linha gerada pela resolução de dependências descrita abaixo — e uma class vazia quando o daemon não tem nome para essa superfície, que um cliente exibe como o text puro em vez de adivinhar a correspondência mais próxima. Os arquivos que a escrita encontra no diretório de saída, ou em um diretório abaixo dele no qual escreveu um arquivo ou pelo qual passou, e que este build não escreveu são deixados onde estão e nomeados em um único aviso depois dos da própria execução, sob uma class vazia, na frase com que aggrega build imprime seu alerta — veja Arquivos que o build não escreveu; files nunca os nomeia. outputParent diz para onde vão os artefatos dentro do workspace, e seu nome é tudo o que ele significa: é o diretório dentro do qual o diretório de saída é criado, de modo que enviar docs escreve os artefatos em docs/dist e não no próprio docs — exatamente o que um build executado em docs em um terminal produz. Se você o omitir, o build escreve onde escreve uma execução na raiz do workspace. Ele se lê de forma diferente do outputDir que as outras solicitações de escrita daqui aceitam, e de propósito: aquelas 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. Ainda assim é um destino dentro do workspace, de modo que um valor absoluto, um que sobe para fora da raiz e um que sai dela por meio de um link — um diretório vinculado 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 arquivo que o build escreve ali, também ficam restritos ao workspace: quando um deles sai do workspace por meio de um link, o build é recusado com 1004 e a frase própria da condição, que nomeia o link e para onde ele leva, e nada é limpo ou escrito. autoPull resolve as dependências da Release antes da renderização, a mesma resolução que aggrega/resolveDependencies realiza, e fica desativado a menos que uma solicitação o peça, em linha com o padrão da própria linha de comando; sem ele, uma Release que não tem lockfile é recusada com o erro lockfile-absent, que nomeia o que executar. Com autoPull definido, esta solicitação acessa registries e escreve o lockfile — veja Acessar um registry, e escrever. Uma solicitação que resolve primeiro ainda renderiza a Release uma única vez: descobrir quais referências remotas uma Release consome já é em si uma renderização, de modo que a resolução já renderizou aquilo de que trata o build, e o build é respondido a partir dessa renderização em vez de repeti-la. policyInput nomeia um diretório dentro do workspace, relativo à sua raiz, no qual o build também escreve o payload que cada papel de governança entrega a um plugin anexado ali — os arquivos que aggrega build --policy-input escreve, com os mesmos nomes —, quer o build termine, quer pare; as notices da resposta dizem então quantos foram escritos e nomeiam cada papel para o qual nenhum arquivo foi escrito, sob uma class vazia. Em uma solicitação que falha, os arquivos escritos estão em disco e esse relato não está na resposta: o envelope de erro traz apenas a recusa. É um destino, de modo que um valor absoluto ou um que sobe para fora do workspace é recusado antes que qualquer coisa seja executada.
  • aggrega/buildPreview — informa o que um build da Release escreveria, sem escrever nada disso. release traz o mesmo contrato descrito acima. Ele executa o mesmo cálculo que aggrega/build, sob as mesmas verificações, de modo que uma Release ou seria recusada por ambos ou é informada por ambos — e é isso 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 um link que sai do diretório dentro do qual suas leituras devem permanecer, é recusado da mesma forma, antes que qualquer coisa seja renderizada, e o mesmo vale para um diretório que a configuração do workspace lista e que não é um diretório, como em aggrega/build. A resposta traz files, os nomes relativos à saída que um build emitiria, ordenados, junto com quaisquer notices; não há outputDirectory, porque nada foi escrito em lugar nenhum que possa ser nomeado. Uma Release que recusa durante a renderização é respondida e publicada exatamente como aggrega/build a responde e a publica. Ele recusa autoPull com um erro invalid-params que nomeia o que enviar no lugar: preencher dependências escreve o lockfile, e esta solicitação não escreve nenhum lockfile. Ele não alcança nenhum registry. policyInput é a única escrita que ele faz, e só quando enviado: escreve os payloads de governança nesse diretório exatamente como aggrega/build faz — os arquivos que aggrega build --dry-run --policy-input escreve —, deixando intactos o diretório de saída e o lockfile, com o mesmo relato nas notices e o mesmo limite: em uma solicitação que falha, os arquivos escritos estão em disco e o relato não está na resposta.
  • aggrega/resolveDependencies — resolve as dependências de catálogo e de origem da Release no cache, fixa as entradas externas que sua renderização consome no armazenamento endereçado por conteúdo e escreve seu lockfile. release é um caminho relativo à raiz do workspace, o mesmo valor que aggrega/irGraph recebe, e é recusado nas mesmas formas. upgrade descarta as fixações registradas e resolve novamente, levando cada dependência à versão mais alta disponível; targets restringe isso às referências de entidade que nomeia, mantendo todas as outras fixações. verify compara a resolução registrada com aquela que esta solicitação realizaria sem ele, respeitando da mesma forma as fixações registradas, e não escreve nenhum lockfile, registro de confiança de plugins ou entity.lock — o cache é lido e preenchido como seria sem ele — respondendo verified: true e o toolchain que o lockfile registra. verify é recusado como parâmetros inválidos junto com upgrade, junto com targets e junto com pinSources, qualquer que seja o valor que traga, antes que qualquer coisa seja resolvida ou qualquer progresso seja informado: um upgrade descarta as fixações que um verify existe para respeitar, alvos nomeados só são resolvidos novamente por um upgrade, e pinSources decide se uma resolução registra as fixações que faltam em um entity.lock ou recusa por causa delas, e nenhuma dessas coisas é feita por uma comparação que não escreve nenhum entity.lock. A linha de comando e a ferramenta do assistente recusam os mesmos pares. A resposta nomeia o lockfile que escreveu ou com o qual comparou e cada referência que fixou, em entities, libraries e plugins, cada entrada trazendo a version para a qual se resolveu e sua source — de onde esta execução obteve a referência, na palavra que aggrega pull --detail imprime para a mesma resolução: fetched-fresh, cache-reuse, local, in-binary ou external — junto com sourceArtifacts, trustedPlugins, externalInputs — quantas entradas externas o lockfile fixa quando a execução termina, contando tanto as mantidas quanto as que esta execução descobriu — e quaisquer notices que a resolução tenha gerado. 🔴 Uma resposta bem-sucedida não significa, por si só, que a fixação das entradas externas esteja completa. Onde a execução fixou todas as dependências, mas não conseguiu terminar de descobrir quais entradas externas a Release consome, ela responde com incompleteExternalInputs dizendo o que interrompeu a descoberta, e ainda assim responde como sucesso — as fixações de dependências estão completas e em disco, então informar a solicitação inteira como falha diria a você para refazer um trabalho que já está correto. Leia esse campo antes de tratar um lockfile como totalmente fixado: ele fica ausente quando nada ficou sem ser descoberto, então sua presença é o sinal. Não há parâmetro de diretório de catálogo: a pilha de busca é a que o workspace configura. Esta é a única solicitação de fixação da sessão para uma Release, e é onde as entradas externas também são fixadas — quais URLs uma renderização consome decorre do que ela renderiza, então esta solicitação renderiza a Release para descobrir, e uma solicitação de build é depois atendida a partir do que ela registrou. Uma Recipe ou FeatureRecipe que a Release constrói cujo entity.lock não registra nenhuma fixação para uma entrada que a entidade lê faz a solicitação ser recusada, nomeando aggrega pin e cada entrada não registrada; pinSources: true executa em vez disso essa etapa de fixação sobre essas entidades, escrevendo o entity.lock ao lado de cada uma — a mesma etapa que aggrega/pin executa, escrevendo os mesmos bytes. Ausente, pinSources segue o pin_sources_at_pull do workspace; enviado, substitui essa configuração nos dois sentidos, de modo que false recusa mesmo em um workspace configurado para fixar. Esta solicitação alcança registries e escreve — consulte Alcançar um registry, e escrever.
  • aggrega/pin — registra, no entity.lock ao lado de uma Recipe ou FeatureRecipe, a fixação de conteúdo de cada entrada que a entidade lê de fora do próprio documento: uma origem remota cujas coordenadas estão escritas por completo, um arquivo que uma entrada artifacts importa e cada arquivo que uma origem local contribui para o que uma publicação da entidade traz. É a mesma etapa que aggrega pin executa em um terminal, e escreve os mesmos bytes. entity é obrigatório e é um caminho relativo à raiz do workspace que nomeia o documento da entidade, recusado nas mesmas três formas que release. Nenhuma Release é nomeada: uma origem remota cujas coordenadas não trazem template nomeia um único artefato para cada Release que usa a entidade, então nada do que uma Release fornece é necessário para fixá-la, enquanto uma origem remota cujas coordenadas vêm de um template é fixada por Release por aggrega/resolveDependencies; uma origem local escrita como template contribui com cada arquivo do diretório da entidade, e cada um deles é fixado aqui. dryRun resolve as entradas e responde com o lock que a etapa escreveria como content, sem escrever nada ao lado da entidade; o cache de conteúdo ainda é preenchido. A resposta traz entity, kind, name e pinnable — false para um tipo que não lê nada que um lock registre, caso em que nada ao lado da entidade foi tocado e todos os outros campos ficam ausentes — e, caso contrário, o lock que escreveu, changed (false quando o lock já registrava todas as fixações e foi deixado idêntico byte a byte), removed onde a entidade agora não lê nada que um lock registre e seu lock foi excluído, e pins, uma entrada por classe de fixação com a contagem que o lock contém. O próprio arquivo da entidade nunca é escrito. Isto escreve ao lado da entidade, dentro do workspace, e alcança os hosts que as origens da entidade nomeiam — consulte Alcançar um registry, e escrever.
  • aggrega/cacheStatus — o que os caches em disco contêm: uma entrada por elemento em cache, com seu tamanho e, onde houver, seu digest de conteúdo, agrupadas por classe. Recebe o workspace e nada mais. Cada classe traz um reach — workspace para o cache de artefatos sob o próprio diretório de cache deste workspace, machine para os armazenamentos de módulos compilados, de descrições de plugins e de pacotes de documentação que todos os projetos da máquina compartilham — e scope nomeia diretamente as classes de toda a máquina. Não escreve nada. Consulte Alcançar um registry, e escrever para saber por que o alcance está em uma resposta que não muda nada.
  • aggrega/cachePrune, aggrega/cacheEvict, aggrega/cacheClear — recuperam o espaço do conteúdo em cache. Um prune remove o que nenhum lockfile de workspace referencia; uma eviction reduz o armazenamento de módulos compilados a maxSize, uma quantidade de bytes escrita como a linha de comando a escreve (5GiB, 512MiB ou uma contagem de bytes); um clear esvazia todos os caches a que esta sessão se refere. Cada resposta nomeia o que removeu, com cada remoção trazendo o reach da classe de onde veio, e cada uma traz scope. Cada resposta também nomeia o que deixou no lugar porque outro processo o mantinha aberto — o Windows se recusa a remover um arquivo aberto, e a operação continua com o restante em vez de falhar: um prune ou uma eviction lista essas entradas em heldOpen, e um clear conta, para cada cache que esvaziou, os arquivos que deixou em heldOpenFiles e seu tamanho em heldOpenBytes. Nos demais sistemas a lista fica vazia e as contagens são zero, e uma execução posterior pode recuperar o que ficou. Estas vão além do workspace — consulte Alcançar um registry, e escrever.
  • aggrega/registryList — os registries que este workspace está configurado para alcançar: para cada entrada, o host, o alias opcional, se é o padrão, sua postura de confiança como campos separados e se há uma credencial para esse host. Recebe o workspace e nada mais. Não contata nenhum registry. O estado da credencial informa apenas a presença — nunca a credencial, nunca seu formato, e nunca se o registry 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 que credentialStateIsMachineWide diz explicitamente.
  • aggrega/search — pesquisa o índice local dos registries configurados. Todo campo restringe a pesquisa e todos são opcionais, então um objeto params vazio pede tudo o que o índice contém. Não contata nenhuma rede: o índice é o snapshot offline escrito sob o próprio diretório de cache deste workspace. A versão informada é aquela que uma resolução escolheria — uma versão cuja retirada traz uma assinatura em que este workspace confia é excluída e nomeada em retracted — e a resposta traz sua própria procedência: indexes dá a idade do snapshot de cada registry pesquisado, stale marca aquele que vale a pena atualizar e missingIndexHosts nomeia registries configurados sem índice local, cujo conteúdo está, portanto, ausente da resposta.
  • aggrega/registryAdd — registra um registry e sua política de confiança de assinaturas. host é obrigatório; todo o resto molda a política ou o destino da escrita. keyPath e trustedRoot nomeiam arquivos: um valor absoluto — um arquivo escolhido em uma caixa de diálogo, por exemplo — é lido onde aponta; um relativo nomeia um arquivo dentro do workspace, resolvido em relação à raiz do workspace em vez de em relação ao diretório em que o daemon é executado, e um que sobe para fora da raiz ou sai dela por meio de um link é recusado com o erro invalid-params antes que qualquer coisa seja lida ou escrita. Um trustedRoot relativo é registrado como o arquivo que nomeia no workspace, de modo que a entrada nomeia esse arquivo independentemente do diretório em que uma verificação posterior seja executada. fetchTrust tem true como padrão quando a chave está ausente, como na linha de comando, e adota no primeiro contato a política anunciada pelo próprio registry; trust na resposta diz o que aconteceu — a política foi fixada, o registry não anunciava nenhuma (e, com unreachable ao lado, não pôde ser alcançado de forma alguma), a linha de base embutida do hub oficial foi fixada em seu lugar, ou nenhuma busca foi tentada. O registro é o mesmo que aggrega registry add realiza: a mesma busca sob a mesma postura de rede, escrevendo a mesma entrada byte a byte. Em um workspace offline, a busca é recusada antes de qualquer conexão, então o registry nunca é consultado, e um registry diferente do hub oficial é recusado, a menos que a solicitação forneça identities ou keyPath, que registram exatamente o que foi enviado e não fazem nenhuma busca: a mensagem do erro é a frase que a linha de comando imprime, precedida pelo código curto da condição E0310 — assim como a mensagem de toda recusa desta solicitação que nomeia uma condição começa com seu código curto — e nada é escrito. O hub oficial ainda é escrito com sua linha de base embutida, respondido com trust.baseline true e trust.reason dizendo que o hub não foi consultado sobre sua política de confiança porque o workspace está offline — o motivo com que começa o aviso da linha de comando — e sem notAdvertised, porque o hub nunca foi consultado. Isto escreve a configuração global por padrão — consulte Alcançar um registry, e escrever.
  • aggrega/registryRemove — remove a entrada de um registry, indicado por host ou alias amigável. Um token que não corresponde a nada é recusado em vez de ser respondido como sucesso sobre uma configuração inalterada. Isto escreve a configuração global por padrão — consulte Alcançar um registry, e escrever.
  • aggrega/logout — remove a credencial armazenada para um registry, a mesma remoção que aggrega logout realiza em um terminal. registry é obrigatório e nomeia o host do registry como você se autenticou nele; não há alias amigável a resolver aqui, porque o armazenamento de credenciais é indexado pelo endereço no qual um cliente se autentica, e não por algo que uma configuração nomeie, então um host que nenhum workspace configura ainda pode ter uma credencial que você pode remover. Um host para o qual o armazenamento não tem credencial é removido com sucesso e nada é reescrito — quem pediu que um host não tivesse credencial obteve o que pediu, então isso é uma resposta e não um erro, e é também o que o comando do terminal faz. A resposta traz registry e scope. Ela não traz nenhuma parte da credencial em nenhuma forma e não informa nada sobre se havia uma: estabelecer isso exigiria uma segunda leitura do armazenamento que ninguém pediu, então consulte aggrega/registryList quando a questão for a presença. Não contata nenhum registry — remover uma credencial armazenada é um ato local, e não se pergunta se esse registry teria aceitado a credencial. Isto altera o armazenamento de credenciais que todos os projetos da máquina compartilham — consulte Alcançar um registry, e escrever.
  • aggrega/registryUpdate — atualiza o índice local pesquisável que aggrega/search lê. Um registry ausente atualiza todos os configurados; nomear um atualiza apenas esse registry. upgrade relê integralmente todos os repositórios, sem comparar nada com o índice já escrito; uma atualização sem ele já relê tudo o que mudou. A resposta traz a contagem de registros de cada host, os repositórios que não conseguiu ler — cada um com um reason que começa pelo tipo da última falha da leitura, onde houver uma —, readsRetried, quantas de suas leituras o registry recusou ou interrompeu pelo caminho e foram pedidas novamente, cada uma contada uma vez e zero incluído, os marcadores de descontinuação que encontrou, o error de um host que falhou — com unreachable ao lado onde esse registry não pôde ser alcançado — e indexRoot, o diretório sob o próprio cache deste workspace em que os índices foram escritos. Isto alcança todo registry que atualiza — consulte Alcançar um registry, e escrever.
  • aggrega/publishEntity — empacota uma entidade do catálogo e a publica em um registro. entity é um caminho relativo à raiz do workspace que nomeia o documento a publicar, recusado nas mesmas três formas que release: ausente, absoluto ou resolvido fora da raiz. Uma entidade Plugin também precisa de plugin, o mesmo tipo de caminho, que nomeia o executável publicado dentro do manifesto da própria entidade. registry é o destino e, por padrão, é o configurado no workspace. dryRun calcula o bundle e o digest em que uma publicação dele resultaria, e não contata nenhum registro. Omitir sign segue a política do próprio registro de destino, que é o que a linha de comando faz quando seu flag está ausente, enquanto enviá-lo é escolha de quem chama — e nenhum dos dois atenua a recusa, porque uma política do registro ou do workspace que exige uma assinatura recusa uma publicação não assinada, diga o campo o que disser. pinSources: true executa a etapa de pin do autor da entidade sobre a entidade antes que ela seja empacotada, de modo que o entity.lock que a etapa grava ao lado dela faz parte do que é publicado — a mesma etapa que aggrega/pin executa. Ela é executada antes de qualquer recusa que avalie o conteúdo da entidade — uma política de assinatura, a proteção de imutabilidade —, de modo que uma publicação recusada nesse ponto ainda deixa o lock gravado; uma recusa sobre a própria solicitação, como um workspace offline ou a ausência de destino, vem primeiro e não fixa nada, assim como a recusa de uma entidade que compartilha seu diretório com outra entidade, no qual a etapa não deve gravar um lock. Se ausente, segue a configuração pin_sources_at_push do workspace; se enviado, substitui essa configuração nos dois sentidos. Com dryRun, a etapa informa o lock que gravaria e não grava nada. Uma publicação que não executa a etapa recusa uma Recipe ou FeatureRecipe cujo entity.lock não registra nenhum pin para uma entrada que ela lê, ou um pin ao qual a entrada não corresponde mais, antes que qualquer coisa seja empacotada — também com dryRun —, nomeando aggrega pin, pinSources e pin_sources_at_push; é a recusa que aggrega/resolveDependencies gera sobre o mesmo lock. A resposta traz reference, tag, kind, mediaType, o par size, o digest publicado — com dryRun, o digest em que essa publicação resultaria, o que aggrega push --dry-run imprime —, signed, alreadyPublished, dryRun e reach; pin — a mesma resposta que aggrega/pin dá — onde a etapa foi executada; e wholeDirectorySource onde a fonte local da entidade é escrita como template, nomeando essa fonte como foi escrita. Uma fonte assim só escolhe seu diretório quando uma Release preenche o template, de modo que a publicação leva todos os arquivos do diretório da entidade, e não apenas os arquivos que a entidade nomeia, e esse campo é como quem chama fica sabendo que isso aconteceu — também em uma execução de teste. Ela também traz windowsUnusableEntries onde o arquivo compactado que a publicação leva contém entradas que o Windows não consegue manter como estão escritas — um caminho com uma parte nomeada como um dispositivo, como CON, AUX ou NUL, em qualquer combinação de maiúsculas e minúsculas e com qualquer extensão em seguida, ou uma parte que termina em ponto ou espaço —, nomeando cada uma, primeiro o nome de arquivo do próprio documento da entidade, depois os arquivos que ele leva; o campo está ausente onde não há nenhuma, o que inclui uma entidade publicada apenas como seu documento. O aggrega em execução no Windows se recusa a descompactar uma entrada assim, de modo que um workspace no Windows não pode usar a versão. Essas são as entradas sobre as quais aggrega push emite avisos, e uma solicitação que pediu para receber relatórios lê as mesmas linhas de aviso no progresso da publicação; nenhum dos dois recusa nada, de modo que a publicação prossegue ou é recusada exatamente como seria sem elas, também com dryRun. Isto grava em um registro e vai além desta máquina, e com a etapa de pin também grava ao lado da entidade — consulte Acessar um registro e gravar.
  • aggrega/publishArtifact — publica um artefato de dados independente, como um bundle de documentação. file é um caminho relativo à raiz do workspace, sujeito ao mesmo contrato, e seus bytes são publicados literalmente: nenhum envelope de entidade é analisado e nenhum despacho é feito com base em um kind. name e tag nomeiam como ele é publicado, e ambos são obrigatórios. mediaType tem como padrão o tipo de bundle de documentação. A resposta traz reference, tag, mediaType, o par size, o digest publicado, alreadyPublished, dryRun e reach. Não assina nada — um artefato publicado é assinado depois, por referência, com aggrega/signArtifacts, que precisa apenas da referência que esta resposta informa. Isto grava em um registro e vai além desta máquina — consulte Acessar um registro e gravar.
  • aggrega/signArtifacts — assina artefatos já publicados e anexa cada assinatura. references traz um ou mais endereços de registro em vez de caminhos, de modo que não estão sujeitos a nenhum contrato relativo ao workspace; uma lista vazia, ou uma entrada vazia nela, é recusada. Uma única identidade atende ao lote inteiro e é resolvida antes que qualquer referência seja assinada, de modo que um lote sem nenhuma credencial disponível é recusado no início, e não no meio do caminho. O mesmo vale para um lote cujas referências precisariam de credenciais diferentes: uma solicitação não nomeia nenhuma chave, então trata-se da configuração do workspace que nomeia uma chave disponível para o registro de uma referência e nenhuma, ou outra chave, para o de uma segunda — nada é assinado, e a recusa nomeia os registros de cada lado, como descreve References signed together need different signing credentials (Referências assinadas juntas precisam de credenciais de assinatura diferentes). Assinar uma referência em que nada foi publicado é recusado em vez de anexado a nada, e uma referência que já traz uma assinatura que a política de confiança do seu registro verifica é deixada como está e contada como assinada, como descreve aggrega sign. jobs, que é opcional, indica quantas referências são assinadas ao mesmo tempo: se ausente, elas são assinadas uma após a outra, e um valor abaixo de 1 é recusado com o erro invalid-params antes que qualquer referência seja lida. Cada referência ainda é assinada exatamente como seria sozinha, como descreve aggrega sign, e tanto o progresso que a solicitação informa quanto a resposta mantêm a ordem em que as referências foram dadas. A resposta traz signed, em que cada entrada nomeia uma reference e o digest publicado com o qual sua assinatura se compromete, junto com reach; um lote em que qualquer referência falhou é respondido como uma falha que nomeia cada uma delas, e não como um resultado com uma lista mais curta. Isto grava em um registro e vai além desta máquina — consulte Acessar um registro e gravar.
  • aggrega/deprecateArtifact — anexa um marcador de descontinuação assinado a um artefato já publicado. Envie uma única reference com sua severity e seu reason, ou from nomeando um arquivo de lote relativo à raiz do workspace — enviar ambos é recusado. Os campos de conteúdo são obrigatórios em vez de solicitados interativamente: ninguém está acompanhando este fluxo, de modo que uma solicitação sem um deles é recusada indicando o que enviar. Eles pertencem apenas à reference única: um arquivo de lote traz o conteúdo de cada marcador em suas próprias entradas, de modo que uma severity, um reason, um replacement ou uma message enviados ao lado de from são recusados como parâmetro inválido, nomeando cada um dos enviados, em vez de ignorados. As mesmas entradas sem chave que as duas solicitações de assinatura aceitam se aplicam aqui, porque o marcador é assinado pelo próprio digest, e as entradas de um arquivo de lote ficam vinculadas a uma única credencial exatamente como as referências de um lote de assinatura. A resposta traz marked, em que cada entrada nomeia a reference retirada, sua severity, o carimbo issuedOn e o digest do manifesto do próprio marcador — o marcador é anexado como referrer sem tag do artefato que ele retira, de modo que nada mais o endereça —, junto com reach. Isto grava em um registro e vai além desta máquina — consulte Acessar um registro e gravar.
  • aggrega/catalogIndex — o índice de entidades: o kind, o name, a apiVersion, a description, os labels, o arquivo de origem e a origin de cada entidade no workspace que a solicitação nomeou. Aceita o workspace e, opcionalmente, release: o conjunto é uma propriedade dessa raiz do workspace e dos diretórios de catálogo que ela configura ou, com release, dos diretórios que a configuração atribui a essa Release — consulte Responder nos termos de uma Release. Ele abrange os dois lugares de onde uma entidade vem — os documentos do Aggrega sob a raiz do workspace e as Features que os diretórios de catálogo configurados contêm —, porque esta é a superfície com a qual um cliente faz o join quando precisa dos campos descritivos de uma entidade, e um índice que conhecesse apenas um dos dois deixaria parte de cada lista de candidatos impossível de resolver. Um documento do workspace conta como entidade quando declara tanto um kind: quanto um metadata.name e não declara nenhuma apiVersion pertencente ao grupo de outro projeto, de modo que um YAML que por acaso esteja na árvore — o arquivo de valores de um chart, uma configuração de CI, um manifesto do Kubernetes renderizado — é ignorado em vez de listado. Um documento que não declara nenhuma apiVersion é informado: é um documento do Aggrega sem um campo, e vê-lo listado é como você descobre que ele está ali para ser corrigido. Consulte Como uma entidade é endereçada para saber o que origin e um file vazio significam. Nenhum documento atrás de um link que leva para fora da raiz do workspace é lido: um diretório fora da raiz não é percorrido, e um arquivo fora dela não é lido, declare o que declarar, de modo que uma entidade que seu editor mostra sob um link assim não é listada como sendo do próprio workspace — nem oferecida por aggrega/attachCandidates ou aggrega/connectionCandidates, que leem os mesmos documentos, mesmo enquanto seu editor está com esse documento aberto. Isso vale seja o que for que o documento declare. A única exceção é uma Release que a configuração do seu workspace nomeia — como build.authoring_release ou como chave de workspace.releases, avaliada pelo arquivo ao qual o link leva, de modo que nomear o link ou esse arquivo conta da mesma forma —, que é lida a partir do arquivo ao qual o link leva, listada no próprio lugar do link, como aggrega/releaseCandidates a lista, e não nomeada; um arquivo nomeado por uma dessas configurações que declara algo diferente de uma Release não é listado, e seu link é nomeado. Os diretórios de catálogo configurados são a forma como um workspace lê outras entidades mantidas em outro lugar, de modo que um link para um diretório que a configuração lista em catalog_dirs — para o workspace ou para uma Release — não é percorrido como os documentos do próprio workspace e também não é nomeado: a configuração o alcançou, e suas Features são listadas a partir do catálogo, como as de todo diretório de catálogo configurado. As Features listadas a partir dos diretórios de catálogo nunca incluem uma que esteja atrás de um link que leva para fora do diretório dentro do qual as leituras de um diretório de catálogo devem permanecer — o workspace, para um diretório de catálogo dentro dele, ou o próprio diretório, para um que a configuração nomeia fora dele —, de modo que uma entidade que a resposta nomeia como estando atrás de um link que ela não leu nunca é listada também ao lado desse nome. A resposta nomeia cada link desse tipo em unreadLinkedDirs, para um link para um diretório, e em unreadLinkedFiles, para um link cujo próprio nome termina em .yaml ou .yml e que leva a um arquivo — relativo à raiz, onde o link está, na ordem em que o workspace é percorrido —, para que um cliente possa explicar o motivo. Um link que a busca deixa de fora, pelo nome, pela localização ou por um .gitignore, não é nomeado, e em uma resposta nos termos de uma Release também não o é um link sob um diretório de catálogo que apenas outras Releases leem. Um link sob um diretório de catálogo fora do workspace não tem um lugar relativo à raiz em que possa ser nomeado, e não é nomeado. Ambos os campos estão sempre presentes, e vazios quando não há nenhum link desse tipo. Quando o próprio arquivo de configuração do workspace, ou o overlay mantido pela CI ao lado dele, é ele mesmo um link que leva para fora do workspace, esse arquivo é nomeado em unreadLinkedFiles independentemente de como a busca o trate, e o índice é a leitura própria do workspace sem nada configurado — nenhum diretório de catálogo é lido para ele, e um índice nos termos de uma Release é recusado; consulte Raiz do workspace e Release ativa.
  • aggrega/entityDefinition — aquilo em que a entidade nomeada se resolve: seu kind, seu próprio name e sua version, sua description e seu publishScope quando os tem, o file em que foi declarada, a authoredLength do texto escrito pelo autor por trás dela e sua definition como documento YAML com a herança já aplicada. file é informado para todo kind, como um caminho que você pode abrir — relativo à raiz do workspace para um documento dentro dela, absoluto para um fora dela, conforme Como um caminho informado é escrito. Ele fica vazio em um caso: uma entidade resolvida a partir de um registro não tem, nesta máquina, nenhum documento escrito a nomear. authoredLength responde a uma pergunta diferente — quanto texto escrito pelo autor a resolução reteve —, e apenas um Aggregate é servido com algum, então leia os dois separadamente, e não como um par. name é a identidade de uma entidade, escrita da forma como uma entidade referencia outra, e pode trazer um sufixo de versão. Esta é a única solicitação aqui que parte de um nome em vez de um cursor, então é a que você deve fazer quando já sabe a qual 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 se resolve em nada é recusado em vez de respondido com um documento vazio; consulte Diferenciar as duas recusas por nome. name pode, em vez disso, ser uma referência de registro — oci://<host>/<repository>:<tag>, ou @<digest> no lugar de :<tag> —, e a resposta é então a entidade publicada nessa coordenada, lida do seu registro, com published nomeando o que foi lido; consulte Perguntar sobre uma coordenada.
  • aggrega/releaseClosure — o fechamento de dependências de uma Release: quais entidades ela alcança e em quais versões resolvidas, em entities, libraries e plugins, junto com as identidades aggregate e manifest em que seus dois ponteiros se resolveram, quaisquer mappingDiagnostics que a resolução tenha gerado e as deprecations registradas contra o que ela alcançou — em seu lockfile e no registro de confiança de plugins ao lado dele, de modo que um plugin retirado anexado em um papel de veredito é nomeado como é nomeada uma referência fixada retirada. release é um caminho relativo à raiz do workspace que nomeia uma Release dentro dela, o mesmo valor que aggrega/irGraph aceita, recusado nas mesmas formas, e exige um lockfile pelo mesmo motivo. Nada é renderizado. Suas entradas não nomeiam nenhuma source: elas dizem de que a Release depende, não o que uma execução fez, que é o que aggrega/resolveDependencies informa. Consulte Um fechamento não é o grafo, porque um cliente que já recebe o grafo não tem isto.
  • aggrega/attachCandidates — quais Features podem ser anexadas a um nó: aquelas cuja aplicabilidade declarada é satisfeita pelos labels do nó. Envie exatamente uma coordenada. node nomeia um documento do workspace pelo seu metadata.name; graphNode nomeia um nó no grafo compilado de release, pelo id sob o qual esse grafo o indexa; labels traz diretamente um conjunto de labels e não nomeia nada, para um cliente que já tem um. A resposta repete a coordenada para a qual respondeu — vazia quando não havia nenhuma a repetir —, traz nodeLabels, os pares de labels com os quais a correspondência foi avaliada, labelSource, que diz de que tipo de conjunto de labels se trata, e cada candidato como o kind, o name, o arquivo de origem e a origin que o endereçam. Devolver os labels é o que torna a resposta auditável por si mesma: um cliente pode explicar por que uma Feature foi oferecida sem formar sua própria ideia dos labels do nó, que é como a resposta de um cliente e a do compilador acabam divergindo. Para um nó do grafo, as Features oferecidas são as que a Release desse nó alcança. Ao lado de graphNode, connection nomeia uma conexão que o componente desse nó traça — seu socket e seu alias —, e a resposta então também traz slots, cada slot que o socket dessa conexão declara com as Features que podem preenchê-lo, ou noSlotReason onde nenhum pode ser preenchido. Consulte O que uma resposta de candidatos a anexação informa.
  • aggrega/connectionCandidates — ao que a entidade nomeada pode se conectar. node é o metadata.name de uma entidade, a mesma coordenada que aggrega/attachCandidates aceita com esse nome. Consulte O que uma resposta de candidatos a conexão informa abaixo, porque as duas metades da resposta não são igualmente completas e a resposta diz qual é qual.
  • aggrega/insertionPoint — onde, em um documento escrito pelo autor, fica uma nova entrada sob um contêiner nomeado, expresso de forma que um cliente a aplique sem analisar o documento por conta própria. file nomeia um documento que o workspace contém, relativo à raiz do workspace, absoluto ou como seu endereço file://; um documento fora da raiz, como escrito ou por meio de um link que leva para fora dela — para o arquivo ou para um diretório no caminho —, é recusado independentemente da grafia que o nomeie, e quer você tenha ou não uma cópia dele; container é o caminho estrutural da raiz do documento até o contêiner em que a entrada vai, sendo cada elemento uma chave de mapping ou uma posição de sequência escrita em decimal. Esse caminho é você quem fornece — o daemon lê a própria estrutura do documento e nunca deduz onde algo deve ficar a partir do nome que tem. Consulte O que uma resposta de ponto de inserção informa, porque a posição sozinha não basta para aplicar a edição.
  • aggrega/attachmentContainer — em qual documento fica a anexação de uma Feature para um nó, e em qual contêiner dentro dele. graphNode nomeia um nó no grafo compilado de release, pelo id sob o qual esse grafo o indexa, e ambos são obrigatórios: o id de um nó é uma chave do grafo de uma Release e não significa nada sem ela. A resposta traz node, file e container — uma lista de segmentos exatamente na forma que aggrega/insertionPoint aceita, de modo que o par se compõe sem nada a deduzir no meio. Para uma anexação em uma conexão que o componente do nó traça, adicione connection com seu socket, seu alias e o document — aggregate ou release —, e a resposta nomeia o contêiner features próprio dessa conexão nesse documento. Consulte O que uma resposta de contêiner de anexação informa, porque file faz parte da resposta, e não algo que você já sabe.
  • aggrega/connectionAtPosition — dentro da entrada de qual conexão cai uma posição em um Aggregate ou em uma Release, respondido nos termos em que as duas solicitações acima aceitam uma conexão. file nomeia o documento da forma como aggrega/insertionPoint nomeia um, e ele é lido primeiro a partir do que a sessão mantém para ele; position é o lugar nele, uma line e um character contados a partir de zero na codificação da sessão; release nomeia a Release cujo grafo compilado registra as conexões, e é obrigatório também para uma posição no Aggregate, porque um nó do grafo e uma conexão existem apenas em um grafo compilado. A resposta traz graphNode e connection — seu socket, seu alias e o document em que a posição foi lida — para passar sem alterações a aggrega/attachCandidates e aggrega/attachmentContainer, ou noConnectionReason onde nenhuma conexão está escrita ali. Consulte O que uma resposta de conexão em uma posição informa.
  • aggrega/editDocument — aplica uma edição estruturada e delimitada a um documento escrito pelo autor, preservando todo byte que ela não toca. É a outra metade dos dois métodos de localização acima: aqueles dizem onde uma entrada fica e deixam para você compô-la e aplicá-la, este compõe uma e a aplica. edit nomeia qual das quatro — add-component, attach-feature, wire-edge, set-value —, e um valor fora delas é recusado em vez de interpretado; node é o caminho estrutural a partir da raiz do documento, uma lista de segmentos exatamente na forma que aggrega/insertionPoint aceita; name é a chave sob a qual a entrada é escrita e value o que ela contém, cujo significado decorre de edit; socket é lido para wire-edge e ignorado nos demais casos. dryRun faz tudo o que a solicitação simples faz, exceto gravar, respondendo com o documento editado como content, para um cliente que mostra o resultado ao autor primeiro; nada é criado nesse modo e written fica vazio. file nomeia o documento de forma relativa à raiz do workspace ou pelo seu caminho absoluto, e um documento fora da raiz — como escrito, ou por meio de um link que leva para fora dela, para o arquivo ou para um diretório no caminho — é recusado sem que nada seja lido ou gravado. Isto grava o documento que você nomeia, dentro do workspace — não resolve nenhuma dependência, não acessa nenhum registro e não toca a rede em nenhuma das duas formas de entrega, e a gravação depende de o documento composto ser validado com o esquema do seu próprio kind. Consulte O que uma resposta de edição de documento informa, porque o padrão é a gravação e uma recusa deixa o arquivo idêntico byte a byte ao que era.
  • aggrega/releaseCandidates — os documentos Release do workspace que a solicitação nomeou, como caminhos absolutos. Aceita o workspace e nada mais: o conjunto é uma propriedade dessa raiz do workspace. A pertinência é decidida pelo kind do documento — o kind: do arquivo é Release — e não pelo nome do arquivo, de modo que uma Release nomeada sem um prefixo convencional é oferecida, e um arquivo que apenas tem nome de Release não é. É isso que o seletor “qual Release?” de um editor deve listar, porque é o mesmo conjunto do qual a cascata da Release ativa descrita abaixo escolhe. A resposta também traz lockfiles, que mapeia cada Release listada — usando como chave exatamente a string sob a qual releases a lista — para o caminho absoluto do seu lockfile; ele está sempre presente, e é um objeto vazio quando o workspace não contém nenhuma Release. Ela traz também unreadLinkedDirs, nomeando — relativo à raiz, onde o link está — cada link que fica onde a listagem leria um diretório e leva a um diretório fora da raiz do workspace: nenhum diretório fora da raiz é percorrido, de modo que uma Release que seu editor mostra dentro de um deles não é listada, e esse campo é o que permite a um seletor explicar o motivo. Um link para um diretório que a configuração do seu workspace lista em catalog_dirs não é nomeado: a configuração o alcançou, como diretório de catálogo e não como um lugar onde Releases são mantidas. Ele está sempre presente, e vazio quando não há nenhum link desse tipo. Ao lado dele, unreadLinkedFiles nomeia da mesma forma cada link cujo próprio nome termina em .yaml ou .yml e que leva a um arquivo fora da raiz do workspace: nenhum arquivo desse tipo é lido, seja qual for seu conteúdo, de modo que uma Release alcançada apenas por um desses links não é listada, e a etapa da cascata relativa a uma única Release não a conta. A exceção é um arquivo que a configuração do seu workspace nomeia como Release — como build.authoring_release ou como chave de workspace.releases, avaliado pelo arquivo ao qual o link leva, de modo que nomear o link ou esse arquivo conta da mesma forma —, que é lido e listado no próprio lugar do link, e não nomeado, desde que declare uma Release; um que declare qualquer outra coisa não é listado, e seu link é nomeado. Ele está sempre presente, e vazio quando não há nenhum link desse tipo. Quando o próprio arquivo de configuração do workspace, ou o overlay mantido pela CI ao lado dele, é ele mesmo um link que leva para fora do workspace, esse arquivo é nomeado aqui independentemente de como a busca o trate, e a listagem é lida sem nada configurado, de modo que uma Release que a configuração teria nomeado por meio de um link não é listada; consulte Raiz do workspace e Release ativa. Consulte Onde fica o lockfile de uma Release.
  • aggrega/activeRelease — para qual Release o workspace que a solicitação nomeou aponta, como caminho absoluto em um campo release, para um cliente que decide o que selecionar por padrão. Aceita o workspace e nada mais. O campo está sempre presente, e um valor vazio significa que o workspace não aponta para nenhuma — uma resposta bem-sucedida, e não um erro, de modo que um cliente que a atualiza a cada reinício do daemon não é obrigado a tratar um workspace comum como uma falha. Quando o valor está vazio, a resposta também traz reason, um resumo de uma linha do que a cascata procurou, e trace, o relato etapa por etapa; ambos são omitidos quando uma Release foi resolvida. Quando uma Release foi resolvida, a resposta traz em vez disso lockfile, o caminho absoluto do lockfile dessa Release, que é omitido quando nenhuma foi resolvida. A Release que ela nomeia não precisa ser uma das que aggrega/releaseCandidates lista — um marcador pode nomear uma Release em um diretório que essa listagem deixa de fora, como vendor/, ou uma nomeada sem extensão YAML —, então é nesta resposta que um cliente lê o lockfile da Release padrão. Consulte Onde fica o lockfile de uma Release. Pergunte por ela em vez de deduzir a resposta a partir de uma das entradas da cascata: uma entrada que a cascata acabou não usando nomeia uma Release diferente da que ela escolheu. A resposta é calculada quando você pergunta, de modo que perguntar de novo depois de gravar um marcador, editar a configuração ou adicionar um arquivo de Release informa a nova resposta, e não o workspace como estava quando o daemon foi iniciado.
  • aggrega/setActiveRelease — registra uma Release como padrão do workspace que a solicitação nomeou, gravando o marcador .aggrega/active-release desse workspace, e responde exatamente como aggrega/activeRelease responde depois que o marcador é gravado. Aceita o workspace e release: um caminho relativo à raiz do workspace que nomeia uma Release dentro dela, sujeito ao mesmo contrato que o release de aggrega/irGraph — um caminho absoluto, um que sai do workspace e um valor vazio são recusados, assim como um que sai por meio de um link, a menos que a configuração do seu workspace nomeie essa Release. O marcador é uma linha que nomeia a Release de forma relativa à raiz, a forma que a cascata descrita abaixo lê. Ele é gravado dentro do workspace e em nenhum outro lugar: quando .aggrega, ou o próprio marcador, é um link que leva para fora do workspace — exista ou não ainda o lugar para onde ele leva —, a solicitação é recusada com o erro invalid-params, cuja mensagem é a frase da própria 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 grava leva, por meio de um link, para fora do diretório dentro do qual deve permanecer)”), nomeando o link e para onde ele leva, e nada é gravado; um link que permanece dentro do workspace é seguido na gravação. A resposta nomeia aquilo em que a cascata se fixa em vez de repetir o que você enviou, e os dois diferem quando build.authoring_release nomeia uma Release, já que a configuração tem precedência sobre o marcador. Registre um padrão dessa forma em vez de gravar o arquivo você mesmo, para que o lugar onde o marcador vai parar seja avaliado pela regra à qual todo arquivo que o produto grava no workspace está sujeito — consulte O limite do workspace.
  • aggrega/effectiveConfiguration — a configuração em vigor para o workspace que a solicitação nomeou, e a camada de onde veio cada configuração. Aceita o workspace e nada mais: a resposta é uma propriedade desse workspace. layers lista os arquivos de configuração e as substituições de ambiente que contribuíram, começando pela de menor precedência; settings traz cada configuração atribuída com seu nome pontuado, seu valor efetivo e a source que a determinou. Uma source é escrita exatamente como a entrada correspondente em layers, de modo que as duas se combinam diretamente. Consulte O que a resposta de configuração efetiva abrange para saber qual camada uma source nomeia e quais são os limites do que uma linha significa.
  • aggrega/configInit — inicializa uma configuração funcional registrando um registro e sua política de confiança de assinaturas, para que uma máquina nova possa baixar e verificar artefatos assinados sem editar YAML à mão. registry é opcional, e um valor ausente inicializa o hub oficial, o mesmo padrão que aggrega config init usa; o host da resposta nomeia o que foi usado. global e workspace são as substituições do destino de gravação, e enviar ambos é recusado. Ele se recusa a sobrescrever um arquivo de configuração existente, nomeando o arquivo — envie force para prosseguir mesmo assim, o que mescla a entrada do registro ao que já existe e preserva as demais configurações. dryRun faz tudo o que a solicitação simples faz, exceto gravar, respondendo com a configuração inicializada como content, para um cliente que mostra o documento ao autor antes de salvá-lo; nada é criado nesse modo e written é false. A recusa por arquivo existente também se aplica com dryRun, então envie force junto com ele para receber como resposta a mesclagem que uma gravação com sobrescrita produziria. Em um workspace offline, apenas o hub oficial pode ser inicializado: esta solicitação não aceita identidades nem chave, de modo que qualquer outro registro é recusado exatamente como aggrega/registryAdd o recusa, código curto e frase incluídos, e deve ser adicionado por meio dessa solicitação com uma política fornecida à mão. A resposta traz host, scope, trust e written, e existed, true quando o arquivo de configuração já existia — de modo que a entrada do registro é mesclada a ele em vez de um novo arquivo ser criado — e ausente quando o arquivo é criado. Isto grava a configuração global por padrão — consulte Acessar um registro e gravar.
  • aggrega/configCapture — congela a configuração efetiva crítica para o build no arquivo de configuração próprio deste workspace, para que o workspace seja compilado da mesma forma sem a configuração global da máquina por baixo. Não aceita nenhum destino de gravação: o congelamento existe para tornar um workspace autossuficiente, então ele sempre grava o arquivo desse workspace. allPlugins amplia o conjunto congelado dos sockets que determinam a saída renderizada — os bindings de provider e as anexações de governança de transformação de labels — para todo socket de plugin, adicionando os gates de governança de veredito e de linter e o socket de importação. A resposta traz configFile, workspaceRoot, captured, sockets e catalogDirs. Consulte O que uma gravação de configuração deixa para trás, porque a resposta nomeia um documento que agora existe e a próxima ação de um cliente é abri-lo.
  • aggrega/skillsInstall — escreve a skill do Aggrega embutida neste binário na pasta de skills de cada assistente que a solicitação nomeia, a mesma instalação que aggrega skills install realiza em um terminal. agents lista os assistentes por identificador, os identificadores que aggrega/skillsList informa; um identificador dado duas vezes é instalado uma única vez, e onde vários dos assistentes nomeados leem uma mesma pasta compartilhada, a skill é escrita ali uma única vez. Uma instalação de projeto o exige. Uma solicitação com global que não nomeia nenhum instala para os assistentes encontrados nesta máquina, como aggrega skills install --global faz sem --agent — cada um cuja pasta de configuração está no diretório pessoal, ou cujo comando está no PATH do ambiente do daemon — e é recusada sem nada escrito onde nenhum é encontrado; nada é perguntado, e installed nomeia os assistentes para os quais ela escreveu. Sem global, a skill vai para a pasta de projeto de cada assistente dentro do workspace que a solicitação nomeia, nunca para o diretório em que o daemon foi iniciado; com global: true, ela vai para a pasta por usuário de cada assistente sob o diretório pessoal que o ambiente do daemon nomeia (HOME, ou USERPROFILE no Windows). Todo destino é verificado antes que qualquer coisa seja escrita, de modo que uma recusa deixa toda pasta como estava: um identificador para o qual nenhuma pasta de skills é conhecida é recusado nomeando-o e os identificadores existentes, e um arquivo em um destino que não traz a linha de comentário que toda cópia escrita da skill traz é recusado nomeando seu caminho. Uma cópia que traz essa linha — uma que uma instalação anterior escreveu, ou uma obtida do repositório de skills publicado — é substituída, e é assim que um aggrega mais recente atualiza a skill para sua própria versão. Uma pasta de projeto alcançada por meio de um link que sai do workspace é recusada sem nada escrito, como toda escrita que o daemon faz em um workspace — consulte O limite do workspace. A resposta traz skill, installed — uma entrada por pasta escrita, na ordem em que os assistentes foram nomeados, cada uma com os agents que a leem, a folder absoluta e replaced — e scope. Com global, isto escreve pastas que todo projeto na máquina lê — consulte Alcançar um registry, e escrever.
  • aggrega/skillsList — as skills que este binário inclui e todo assistente para o qual aggrega/skillsInstall pode escrevê-las, a listagem que aggrega skills list imprime. Recebe o workspace e nada mais, e não lê nada dele. skills traz o name e a description de cada skill; agents traz o id, o name e a projectFolder de cada assistente — relativa à raiz de um projeto, que nesta superfície é o workspace que uma solicitação nomeia — e a userFolder, 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 registro configurado um plugin de um tipo nomeado e o adiciona à configuração. type e query são ambos obrigatórios: type é um entre provider, governance, linter, importer e cli, e query é comparado com os nomes dos plugins desse tipo e deve se resolver em exatamente um, de modo que uma consulta que corresponde a vários é recusada com os candidatos em vez de resolvida arbitrariamente. capability nomeia a capacidade que um binding provider atende e é obrigatório nesse caso; role nomeia o papel de uma anexação governance — label-transform, ir-verdict ou render-verdict — e é obrigatório nesse caso; cada um é lido apenas para seu próprio tipo e recusado em qualquer outro, porque um campo que silenciosamente não fizesse nada pareceria ter funcionado. acceptCapabilities é obrigatório para cli e confirma as capacidades declaradas desse plugin: o comando no terminal obtém essa decisão perguntando, e esta superfície não tem a quem perguntar, então quem chama a obtém e a envia. global e workspace são as substituições do destino de gravação, e enviar ambos é recusado. dryRun faz tudo o que a solicitação simples faz, exceto gravar, respondendo com a configuração resultante como content; nada é criado ou modificado e written é false. O registro ainda é consultado e a versão ainda é resolvida, porque a identidade nesse conteúdo é a identidade que uma gravação teria fixado. dryRun é recusado no tipo cli, em vez de ignorado: o que a adição de uma extensão de comando registra é o digest do conteúdo dos bytes que ela verificou, um registro que o compilador mantém, e não um conteúdo que alguém edita, e a adição armazena esses bytes em cache à medida que avança — por isso ela é gravada em vez de devolvida. A versão é fixada para você — a consulta se resolve em um plugin, e a versão que ela nomeia como <name>:<version> ou, caso contrário, a versão publicada mais alta dele é gravada na entrada; uma versão nomeada que uma retratação na qual este espaço de trabalho confia retirou é fixada mesmo assim, e a resposta traz withdrawn: true. Isto acessa um registro, e uma adição do tipo cli que não nomeia nenhum dos dois escopos grava a configuração global — consulte Acessar um registro e gravar. Consulte O que uma alteração de plugin informa.
  • aggrega/pluginRemove — remove a entrada de um plugin configurado para que ele deixe de participar. type é o mesmo conjunto que uma adição aceita, e query identifica a entrada: o nome curto do plugin, sua referência fixada ou — para provider — a capacidade que o binding atende. Ambos são obrigatórios. global e workspace são as mesmas substituições do destino de gravação, recusadas em conjunto da mesma forma. Uma consulta que não corresponde a nenhuma entrada é recusada em vez de respondida como um sucesso sobre uma configuração inalterada, de modo que nunca se diz a quem chama que um plugin deixou de participar quando isso não aconteceu, e um erro de digitação nunca remove um plugin diferente. Não contata nenhum registro: uma remoção opera apenas sobre o texto da configuração. Uma remoção do tipo cli que não nomeia nenhum dos dois escopos grava a configuração global — consulte Acessar um registro e gravar. Consulte O que uma alteração de plugin informa.
  • aggrega/pluginSync — alinha os registros mantidos pela máquina de uma entidade Plugin ao 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 da autodescrição do módulo. Nenhum dos dois registros é escrito à mão, porque ambos têm sua fonte de verdade no módulo. Ambos os campos são obrigatórios e nenhum tem valor padrão — os registros são derivados do módulo, então um alinhamento que não nomeia nenhum não tem a que se alinhar —, e ambos são caminhos relativos à raiz do workspace, recusados quando são absolutos ou se resolvem fora dela, como escritos ou por meio de um link. Apenas esses dois blocos mudam: todo outro byte é mantido literalmente, incluindo comentários, linhas em branco e estilo de aspas, e um arquivo que já registra o que o módulo implica é deixado idêntico byte a byte e informado como inalterado. Isto grava o arquivo de entidade que você nomeia, dentro do workspace, e não contata nenhum registro. Consulte O que uma alteração de plugin informa.
  • aggrega/pluginGenCatalog — gera uma entidade Plugin por convidado selecionado, mesclando os campos de contrato derivados da autodescrição do convidado com um overlay por plugin escrito à mão. fromEmbedded e plugin são os dois modos de seleção e exatamente um se aplica: todos os convidados que este binário traz, ou um módulo em um caminho que você indica; indicar ambos, ou nenhum, é recusado em vez de resolvido. overlay é obrigatório, e é um diretório de overlays com fromEmbedded ou um único arquivo de overlay com plugin — quando há vários, um overlay é associado a um convidado pela identidade, e quando há apenas um não há nada a associar. outputDir é obrigatório nas duas formas de entrega, e dryRun não dispensa dele: uma execução de teste muda para onde o conteúdo vai, não de qual arquivo ele é conteúdo, então cada documento retornado continua indicando o caminho a que se destina, e esse caminho é composto a partir deste diretório. Os três caminhos aqui não são julgados da mesma forma, e a distinção segue o que a geração faz com cada um. plugin e overlay são lidos, e ambos são arquivos que você selecionou — um módulo fica no diretório em que sua toolchain o compila, e seu overlay é escrito ao lado dele —, então cada um pode ser absoluto e é lido onde realmente está. Em outputDir se escreve, então ele é relativo à raiz do workspace e é recusado quando é absoluto ou quando se resolve fora dela, como escrito ou por meio de um link — um diretório ainda não criado abaixo de um diretório vinculado que leva para fora é recusado como esse diretório é. Executar de novo sobre entradas inalteradas produz entidades idênticas byte a byte. Isto grava as entidades geradas em outputDir, dentro do workspace, a menos que dryRun as peça como conteúdo. Veja O que uma alteração de plugin informa a você.
  • 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 schema em minúsculas com hífens — component, aggregate, release, recipe, ir, wasm-provider e assim por diante — e é opcional, porque seleciona qual de duas perguntas você está fazendo. Indique um tipo e a resposta traz kind e schema, o schema como documento JSON em vez de uma string que contém um. Não indique nenhum e a resposta traz em vez disso kinds e entityKinds: quais tipos você pode indicar, em duas amplitudes. kinds é cada token que pode ser pedido a este binário, na mesma ordem em que aggrega get-schema --list os imprime. entityKinds é o conjunto mais restrito de tipos dos quais um autor escreve um documento, e cada entrada traz o token kind a ser enviado de volta, o valor documentKind que vai no próprio campo kind: do documento e acceptedBy, que diz se a validação de uma única entidade, a publicação e a inspeção por nome aceitam um documento desse tipo. Veja Quais tipos você pode oferecer a um autor antes de construir um seletor a partir de qualquer um dos dois. A resposta com o schema e a enumeração nunca são combinadas, então é possível ler na resposta qual pergunta foi respondida. Um token ao qual nenhum schema corresponde é recusado com todo o conjunto válido na mensagem, de modo que um erro de digitação é corrigido sem uma segunda chamada. Ele não toma nada do workspace, não contata nenhum registry e não grava nada, então responde em um workspace que não contém absolutamente nada — e é isso que o torna utilizável para ligar a associação de schemas de um editor ao binário que o editor está realmente controlando, em vez de a qualquer cópia dos schemas instalada em outro lugar.
  • aggrega/scaffoldEntity — um documento inicial para um tipo de entidade: exatamente os campos que o schema desse tipo exige, com os valores fixos apiVersion e kind preenchidos e um placeholder em todo lugar onde um valor é necessário. kind é obrigatório e é o token de schema em minúsculas com hífens — component, aggregate, release, recipe, manifest, feature e assim por diante; aggrega/getSchema sem kind informa quais tokens você pode enviar, e um token ao qual nenhum schema corresponde é recusado com esse conjunto na mensagem, de modo que um erro de digitação é corrigido sem uma segunda chamada. Um cliente que oferece ao autor a escolha de um tipo lê entityKinds desse método, que é o conjunto de tipos dos quais um documento pode ser escrito. name é opcional e inicializa metadata.name para os tipos cujo schema exige um. A resposta traz kind e skeleton. Veja O que uma resposta de scaffold lhe dá, porque a resposta é um documento a ser escrito e não um documento que foi escrito. O esqueleto é derivado do mesmo schema que aggrega/getSchema informa, então os dois respondem a partir de uma única fonte. Quando recebe example em vez de kind, o método escreve um dos exemplos executáveis da documentação em um novo diretório do workspace, como aggrega scaffold --example faz em um terminal; quando recebe apenas list: true, ele responde com todos os exemplos existentes e não escreve nada. As duas formas precisam do workspace, então uma solicitação de qualquer uma delas o nomeia em workspaceRoot, e uma que não nomeia nenhum é recusada. dir nomeia o novo diretório relativo à raiz do workspace e, por padrão, é o nome do exemplo; um valor absoluto, ou um que se resolve fora da raiz — como escrito ou por meio de um link — é recusado antes que qualquer coisa seja lida, e um diretório que contém qualquer coisa é recusado e deixado como está. A resposta a uma listagem traz examples, cada um com seu name, level e summary; a resposta a uma escrita traz example, dir, files — cada arquivo escrito, relativo a dir —, next, os comandos que a página do exemplo dá para construí-lo, ausente onde ela não dá nenhum, e version, a versão da documentação da qual o exemplo foi lido. Campos de duas formas enviados juntos — kind com example, list com example ou kind, name com example ou list, ou dir sem example — são recusados antes que qualquer coisa seja lida, com as mesmas palavras com que a ferramenta do assistente os recusa. Uma escrita obtém o pacote de documentação onde a máquina não tem nenhuma cópia que a própria verificação de assinaturas do workspace admita, e escreve dentro do workspace — consulte Alcançar um registry, e escrever.
  • aggrega/import — transforma a descrição de uma origem externa em rascunhos de arquivos de autoria do Aggrega, a mesma conversão que aggrega import realiza em um terminal. source é obrigatório e indica o arquivo ou o diretório a converter, como caminho absoluto ou relativo à raiz do workspace — uma descrição exportada por outra ferramenta fica onde você a salvou, então ela é lida onde realmente está, e não apenas dentro do workspace. Um diretório é lido como aggrega import lê um: limitado aos arquivos dele que os padrões de arquivo declarados pelo importador selecionam, excluída a pasta de saída de build do workspace, dist/, e restrito a si mesmo onde quer que esteja, de modo que nenhum link dentro dele é seguido para fora. outputDir é opcional e indica o diretório para onde vão os rascunhos, e não segue esse contrato: nele se escreve, então é um caminho dentro do workspace, e um valor absoluto, ou um que se resolve fora da raiz — como escrito, ou por meio de um link, incluindo um diretório ainda não criado abaixo dele — é recusado. Se você o omitir, os rascunhos vão para baixo da raiz do workspace, onde aggrega import os grava quando não indica nenhum destino — também com dryRun. format indica explicitamente o formato da origem; se você o omitir, o formato é reconhecido pelas assinaturas que os importadores declaram — tanto os do catálogo do workspace quanto os importadores principais do compilador —, e uma origem que nenhum reconhece, ou que importadores de mais de um formato reconhecem, é recusada pedindo format em vez de ser adivinhada. target indica uma capability de provider, como compose ou helm — a palavra à qual o spec.capability de uma Recipe se vincula — e gera como rascunho, ao lado dos rascunhos do importador, o Manifest contra o qual a Release em rascunho é construída para esse provider, exatamente como aggrega import --target faz: 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 Aggregate em rascunho compõe — para a Recipe ou a receita de funcionalidade dessa capability que o catálogo do workspace oferece para ele, pelo seu nome qualificado pela capability e sem versão: a única que existe ou, entre várias, a que tem o nome do tipo. O spec.manifest da Release é definido para ele; um tipo sem nenhuma, ou com várias e nenhuma com esse nome, fica sem mapeamento com uma constatação warn que o nomeia, e um mapeamento que o próprio importador gerou é mantido onde o catálogo o oferece para esse tipo e essa capability, e descartado com uma constatação warn caso contrário. Um target ao qual nenhuma Recipe do catálogo se vincula é recusado antes de o importador ser executado, nomeando-o junto com as capabilities às quais as Recipes do catálogo se vinculam, e nada é gravado; se você o omitir, nenhum Manifest é gerado — exceto com sync, que gera o rascunho para o destino que o registro da importação anterior nomeia. Um importador principal que a máquina ainda não tem é baixado pela primeira importação que precisa dele — veja O que uma resposta de importação informa a você. dryRun faz tudo o que a solicitação simples faz, exceto gravar, respondendo com os rascunhos como conteúdo, para um cliente que os mostra primeiro ao autor; nada é criado nesse modo e written fica vazio. sync atualiza em relação à origem o que uma importação anterior gerou em outputDir, alterando apenas o que a importação gravou, como aggrega import --sync faz; sem ele, uma solicitação cujos rascunhos sobrescreveriam um Aggregate já existente é recusada. A resposta traz format, outputDir, written, files, drift, diagnostics, decisions e halted. Veja O que uma resposta de importação informa a você, porque uma origem que o importador não conseguiu converter por completo é uma resposta bem-sucedida e não um erro.
  • aggrega/explainError — o que o compilador declara sobre a condição que um código nomeia, e as entradas publicadas que ensinam a correção na autoria. code é obrigatório e aceita qualquer um dos identificadores de uma condição: o código curto que um diagnóstico traz em shortCode, ou o descritivo em code. É a expansão de um código que os diagnósticos neste canal já trazem, e é a mesma resposta que aggrega explain imprime em um terminal. A resposta sempre traz a condição — shortCode, code e message —, porque essa parte é declarada dentro do binário e não precisa de rede; entries traz o passo a passo publicado, e note diz por que ele está ausente, onde estiver. 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 workspace admita — veja Alcançar um registry e gravar. Veja Expandir um código que um diagnóstico trazia.
  • aggrega/invalidate — um sinal de invalidação de cache vindo do observador de arquivos do editor.

Notificações:

  • $/cancelRequest — do cliente para o servidor: interrompe a solicitação em andamento enviada com esse id. O daemon cancela o trabalho dessa solicitação; uma operação percebe o cancelamento no próximo limite de etapa, e não instantaneamente, então o trabalho já em andamento continua por um momento. Cancelar um id para o qual nada está em execução é uma operação nula segura.
  • $/progress — do servidor para o cliente: o que uma operação longa está fazendo enquanto faz, no token em que a solicitação pediu para receber relatórios. Enviado apenas para uma solicitação que trazia um. Veja Acompanhar uma operação longa.
  • aggrega/shutdown — inicia um esvaziamento cooperativo: as solicitações em andamento terminam, as novas solicitações são recusadas e então o daemon é encerrado.
  • aggrega/publishDiagnostics — um conjunto de diagnósticos enviado pelo servidor (usado para avisos de divergência do lockfile e para o estado na inicialização). Cada entrada traz um source que nomeia qual das camadas de diagnóstico do daemon a gerou: aggrega para uma constatação sobre os documentos escritos, aggrega-build para um aviso que uma build gerou — cada aviso que ela gerou, que é o mesmo conjunto que aggrega build imprime — e aggrega-lint para uma constatação sobre as convenções de publicação, as mesmas constatações que aggrega lint imprime. O campo está sempre presente em cada entrada, então um cliente pode agrupá-las em vez de mostrar uma única lista indiferenciada, e nunca precisa distinguir uma origem ausente de uma das camadas. Um frame é enviado para um arquivo apenas quando seu conjunto difere daquele de que este cliente foi informado por último, então uma solicitação que recalcula as mesmas constatações não envia nada; o primeiro frame de um arquivo, e um frame que esvazia o conjunto de um arquivo, são ambos diferenças e são sempre enviados.

Pedir ao próprio processo que pare alcança o daemon nas mesmas condições. Uma interrupção vinda de um terminal, ou uma solicitação de encerramento vinda de um supervisor ou de um runtime de contêineres, inicia o esvaziamento que aggrega/shutdown inicia: as solicitações em andamento terminam, as novas solicitações são recusadas e então o daemon é encerrado. Uma segunda solicitação encerra o processo imediatamente. Um cliente que inicia o daemon pode pará-lo de qualquer uma das formas, e um que o para pelo protocolo e um que lhe envia um sinal obtêm o mesmo esvaziamento.

Validação em tempo real

A cada aggrega/validate, o daemon valida o buffer do editor contra o schema do documento e retorna diagnósticos apontando para a chave problemática — o mesmo veredito que uma build daria, sobre conteúdo não salvo. Uma solicitação que não envia content pergunta sobre o arquivo como ele está em disco; um content enviado vazio é um buffer vazio, não uma solicitação do arquivo. Um arquivo enviado sem seu conteúdo precisa ser um que o workspace contenha e que possa ser lido — um arquivo fora do workspace, um alcançado por meio de um link que leva 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 trazem tal cabeçalho — a configuração do workspace .aggrega-config.yaml e o lockfile da Release que a solicitação nomeou — são reconhecidos pelo nome do arquivo, de modo que uma chave lixo ou malformada em qualquer um deles também é sublinhada em tempo real. Arquivos que não são documentos do Aggrega — templates de charts do Helm, arquivos do Compose, manifestos do Kubernetes e arquivos .lock de outros ecossistemas, como Cargo.lock ou flake.lock — não recebem diagnósticos; o daemon nunca informa nada sobre arquivos alheios.

Um placeholder ainda pendente é nomeado em sua chave, com o que ele aceita. Uma entidade de catálogo de um tipo que aggrega validate verifica como entidade única também é lida em busca dos valores obrigatórios que deixa como string vazia, pela leitura que esse comando aplica, de modo que o daemon nomeia cada placeholder que o comando nomeia para os mesmos bytes. Cada placeholder é uma entrada: seu message diz que a chave é um placeholder ainda pendente, seu suggest diz o que o valor aceita, e seu keyPath traz o caminho com pontos da chave. A entrada substitui a constatação do próprio schema para esse valor vazio, e todas as demais constatações sobre o documento são informadas como a verificação do schema as informa. Um placeholder que o schema admite vazio também é nomeado, embora a verificação do schema não informe nada sobre ele — capability e implements de uma Recipe ou FeatureRecipe em rascunho são os que você vai encontrar. Onde a verificação do schema também recusa o documento, cada entrada traz o código dessa verificação, E0215, e onde ela o aceita, as entradas não trazem código: os mesmos identificadores que o relatório do comando traz para esses bytes. Uma entrada é desenhada na chave que contém o valor vazio, na linha em que o comando a nomeia — mesmo em uma chave cujo próprio nome contém um ponto, como o label component.aggrega.ai/type, em que uma constatação que a verificação do schema informa sobre essa chave é desenhada na chave que a envolve —, e keyPath nomeia a chave por completo. Isso vale quer a solicitação nomeie uma Release ou não, porque é uma pergunta que o documento responde por si só, e a um documento que ainda deve um valor ainda não se pergunta sobre as convenções de publicação: essa camada é limpa para ele, como ocorre com um documento cuja forma o schema recusa.

Cada solicitação nomeia a Release a que se refere, e o daemon não guarda nenhuma própria. As verificações semânticas resolvem o fechamento de dependências dessa Release e leem o lockfile dessa Release para obter seus pins — ou, para uma entidade de catálogo, leem os diretórios de catálogo com os quais essa Release é construída, como descreve o próximo parágrafo —, então duas solicitações que nomeiam duas Releases são respondidas sobre a Release que cada uma nomeou. Nada passa de uma para a outra: não há uma Release selecionada a mudar, e mudar a Release contra a qual você valida é um valor diferente na próxima solicitação, e não algo que o daemon precise ser instruído a esquecer.

Uma entidade de catálogo nomeada junto com uma Release é verificada como entidade única, nos termos dessa Release. Um file que contém 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 salvo do editor: suas referências — o Component que uma Recipe implementa, uma biblioteca a que um pilar se refere — são resolvidas pelos diretórios de catálogo que a configuração do workspace atribui a essa Release, então um mesmo arquivo pode estar limpo nos termos da Release que é construída com ele e falhar nos termos de uma Release cujos diretórios não contêm aquilo a que ele se refere. Esse é o veredito que a linha de comando e a ferramenta validate de aggrega mcp dão para a mesma entidade ao lado da mesma Release e, como o delas, não percorre nenhum fechamento e não lê nenhum lockfile. Uma constatação bloqueante é uma entrada de erro com as próprias palavras da verificação e trazendo seus códigos, desenhada na chave que ela nomeia na entidade e, onde não nomeia nenhuma, na chave kind: da entidade, como descreve O que uma entrada de diagnóstico traz — a menos que uma build já informe essa falha no arquivo, caso em que a entrada da build é o único relato; um aviso que a verificação gera ao ler o catálogo é uma entrada de alerta antes dela; uma verificação limpa sobre diretórios que existem todos não retorna nenhuma entrada. Uma asserção com falha — uma que chama fail, na Recipe ou no Component que ela implementa — não é aqui uma constatação bloqueante, mas uma entrada de alerta, com as palavras da verificação e trazendo seus códigos, encerrada pela frase A Release must satisfy this assertion before a build of it can pass., e desenhada onde a constatação bloqueante estaria: a asserção de uma Recipe na própria chave dessa asserção sob assertions, a de um Component na chave kind: da Recipe. Como uma constatação bloqueante, ela cede lugar à entrada de uma build que informa a mesma falha no arquivo. A verificação constrói a entidade em torno de placeholders e valores padrão do schema em vez dos valores que uma Release define, então não consegue distinguir uma asserção que espera por uma Release de uma que está quebrada, e deixa o veredito para uma build, que informa a mesma asserção como erro (uma asserção com falha é um alerta). Um diretório que a configuração do workspace lista para a Release e que não é um diretório — nada existe ali, por exemplo — interrompe a verificação: o arquivo traz uma única entrada de erro no lugar do veredito da verificação, a recusa que todo comando dá a esse diretório, nomeando a entrada, o arquivo de configuração e a linha que a lista, e a opção (De onde as entidades locais são lidas). Uma release que não nomeia nenhum arquivo, ou que nomeia um diretório, recebe resposta no arquivo com a frase com que a linha de comando a recusa, em vez de ser verificada nos termos do workspace. O que uma build de uma única entidade não consegue substituir é julgado como a linha de comando o julga, e o que a linha de comando deixa de lado ou não verifica não gera entrada aqui — veja o que a correção de uma entidade única não verifica e, para uma Recipe cujo template lê um valor que apenas uma aresta da topologia ou uma credencial anexada fornece, correção de uma 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; para eles ficam as verificações do fechamento descritas acima. Um buffer com conteúdo Workload é lido como YAML que não é um documento do Aggrega, porque esse conteúdo é escrito dentro do campo workload: de uma Recipe ou de uma FeatureRecipe e é verificado ali, onde está; a linha de comando e a ferramenta validate, ao receberem um arquivo Workload por caminho, verificam sua forma isoladamente.

Nomear uma Release é opcional, e a resposta diz qual das duas coisas você pediu. Nomeie uma e você recebe tudo o que foi descrito acima. Não nomeie nenhuma e você recebe as verificações que um documento responde por si só — se ele pode ser analisado, se sua própria forma é admissível e, para uma entidade de catálogo de um tipo validado como entidade única, quais placeholders ele ainda deve —, sem resolver nenhuma Release, percorrer nenhum fechamento nem ler nenhum lockfile; a resposta traz então checked: "document". Nomeie uma Release e essa chave fica ausente, porque essa resposta é o veredito completo do método e não tem nada a qualificar.

Leia a chave em vez de deduzir 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 o que um veredito completo limpo responde, então 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 a solicitação nomeou, então uma solicitação que não nomeia nenhuma não reconhece nenhum lockfile e não informa nada sobre um.

Um workspace que não contém nenhuma Release recebe resposta em vez de recusa, e é isso que mantém o resto do daemon utilizável ali. A validação é o que alimenta o cache de análise que toda outra operação de arquivo lê, então um repositório só de catálogo, um scaffold com um único Aggregate ou um diretório de rascunho continuam recebendo hover, autocompletar, ir para a definição, referências, implementações e diagnósticos em cache. Recusar levaria tudo isso junto, justamente nos workspaces em que um cliente não tem nenhuma Release a nomear.

O que uma entrada de diagnóstico traz

Cada entrada se posiciona com line e column, ambos com base 1 na codificação de posição negociada no handshake, e adiciona end_line e end_column quando abrange um token inteiro. message é o texto que um cliente mostra ao usuário, severity o classifica, e source nomeia qual das camadas do daemon a gerou, como descrito acima.

As camadas respondem a perguntas diferentes sobre um mesmo arquivo, então uma entrada de cada uma pode estar na mesma linha sem que uma seja duplicata da outra: uma diz que o deployment não está correto, outra que a entidade não pode ser publicada. Um cliente que as mostrasse como uma única lista informaria um único problema duas vezes, e ler source é o que as separa.

Onde uma entrada fica depende do assunto dela, e não de qual camada a gerou. Uma constatação sobre algo que o autor escreveu é posicionada na chave sob a qual ele o escreveu, para que o editor a desenhe onde a edição deve ser feita. Uma constatação sobre a forma da topologia implantada nomeia um componente e uma chave de entrega em vez de uma linha — essas são coordenadas na topologia implantada, não no documento —, então ela é desenhada na chave kind: do documento e nomeia suas coordenadas na mensagem. Os dois tipos chegam à camada aggrega-build, porque uma build gera ambos. Uma recusa que uma build gerou 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 suas verificações, na chave workload da sua Recipe; a asserção com falha 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 reúne várias, no seu próprio documento e na sua própria chave — e, quando não aponta para nenhum documento, na chave kind: do Aggregate; Uma recusa gerada durante a renderização descreve isso. Então um cliente posiciona cada entrada pelos seus próprios line e column e nunca deduz uma posição a partir da camada.

Uma constatação que não nomeia nenhuma chave que o documento contenha é desenhada na chave que nomeia o documento. Uma constatação que as próprias verificações de um documento geram sobre o que ele diz, a constatação da verificação de entidade única e um aviso ou uma recusa que uma build gera são cada um desenhados na chave que nomeiam; quando não nomeiam nenhuma, ou nomeiam uma chave que o documento não contém, são desenhados na chave kind: do documento, ou no seu metadata.name quando ele não declara nenhum kind:, e no início do arquivo apenas quando o documento não declara nenhum dos dois ou não pode ser analisado. Um documento costuma começar com um comentário — todo arquivo de catálogo traz 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 seu autor escreveu. Uma entrada sobre algo diferente do que o documento diz é posicionada no início do arquivo: uma entrada Dependencies: sobre as dependências da Release, uma etapa que parou sem nomear nada no documento, um lockfile divergente, uma referência que uma renderização teve de recusar, uma Release que não foi carregada — e também uma entrada aggrega-lint cuja regra não calculou nenhuma linha. Onde uma posição é declarada em vez de desenhada, uma constatação que não nomeia nenhuma chave continua sem ter uma: a resposta de erro de uma recusa que não nomeia nenhuma chave traz apenas o documento no seu data.

Em qual documento uma entrada é publicada decorre da mesma regra. Uma validação que nomeia uma Release responde sobre o Aggregate dessa Release, a própria Release, o documento de cada módulo que o Aggregate importa e o Manifest que a Release nomeia. Uma constatação posicionada na Release — a recusa de uma entrada que a Release escreve em uma das conexões de um componente, do dimensionamento que ela dá a essa conexão, de um anexo que ela preenche ou dimensiona ali, de uma conexão que ela liga, de uma Feature que apenas a Release anexa a um componente ou a uma fronteira, ou do infra que ela dá a um anexo — é publicada quando o documento da Release é validado, na chave da Release que a escreveu, e de forma alguma no Aggregate. Uma constatação posicionada no próprio documento de um módulo — a recusa do que um dos componentes do módulo declara, de um socket que seus anexos ligam, de seus valores ou dos valores em suas próprias conexões — é publicada quando o documento desse módulo é validado, na chave que a escreveu ali, e de forma alguma no Aggregate. 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 de extends não pode ser seguida — é publicada quando esse Manifest é validado, na chave da entrada de mapeamento a que se refere, e de forma alguma no Aggregate; quando o texto aberto do Manifest não escreve essa entrada — uma entrada que ele herda por meio do seu próprio extends, ou uma que uma edição não salva removeu —, a constatação é publicada na primeira linha do Manifest. Todas as demais constatações que a validação dessa Release gera são publicadas no Aggregate, entre elas as constatações no nível de dependências que não nomeiam nenhum documento do seu workspace — uma referência ou um plugin retirado, um Component ou uma Feature de catálogo cuja cadeia de extends não se resolve ou cujo schema é inválido, um plugin de gate que não corresponde ao registro de confiança, uma instância de componente que nenhum mapeamento resolve, uma Recipe ou FeatureRecipe cujo provedor não consegue renderizar um tipo de entrada que declara, e os avisos de sobreposição de pilares do schema e de estreitamento na 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, seja qual for a etapa da build que a gerou; um editor que valida cada documento aberto contra a Release mostra cada uma ali. Uma Release cujas dependências não podem ser resolvidas de forma alguma não gera nenhuma dessas constatações, e a falha em resolvê-las é uma única entrada no início do próprio documento da Release e de todo outro documento validado contra ela que o daemon reconhece, como descreve Validação em tempo real, e não verifica como entidade única — seu Aggregate, seu Manifest, uma biblioteca, outra Release, a configuração do workspace —, com o prefixo Dependencies: e trazendo o próprio relato da resolução sobre o que a interrompeu. No próprio documento da Release, a entrada é esse relato e nada mais. Em todo outro documento, ela primeiro diz que o documento é verificado contra essa Release e nomeia a Release como uma solicitação a nomeia — Dependencies: this document is checked against the Release <release>, whose dependencies cannot be resolved: seguido do relato —, porque nada nesse documento diz contra qual Release ele foi verificado: um editor que verifica cada documento aberto contra a única Release selecionada coloca a entrada em documentos que não têm nada a ver com essa Release, e o nome é o que lhe diz que a seleção é a causa. Um arquivo que o daemon não reconhece não traz nenhuma entrada desse tipo, seja qual for a Release nomeada com ele.

Uma resposta traz todas as camadas presentes no arquivo, por mais que a validação tenha avançado. A resposta de aggrega/validate é todo o estado atual do arquivo: o que esta validação encontrou, as entradas aggrega-build que uma build, uma prévia ou uma solicitação de grafo publicou no arquivo, e suas constatações sobre as convenções de publicação, cada uma sob seu próprio source. Uma validação que para no buffer — um que não pode ser analisado, ou um documento cujo envelope o schema recusa — responde da mesma forma: informa sua própria constatação e mantém todas as entradas de build no arquivo, porque não aprendeu nada sobre a build. Então um cliente pode substituir o que mantém para o arquivo, camada por camada, a partir de qualquer resposta.

Uma falha é informada uma única vez. A própria validação de um documento e uma build podem encontrar a mesma falha nele: a verificação de entidade única renderiza uma Recipe que uma build também renderiza, a validação compõe o grafo que uma build compõe, e uma Release cujas dependências não se resolvem faz ambas falharem. Enquanto uma build informa tal falha em um documento, a validação desse documento não a informa uma segunda vez: uma entrada aggrega que nomeia a mesma condição — o mesmo code — que a recusa de uma build no mesmo documento, posicionada no mesmo intervalo ou em nenhuma chave própria — desenhada onde é desenhada uma entrada que não nomeia nenhuma chave, ou no início do arquivo —, é omitida de toda resposta e de toda publicação para esse documento, e o relato da build fica sozinho. O relato da build é 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 se resolve, essa própria resposta — que nada publica — no documento que seu data.file nomeia, senão seu data.lockfile, senão a Release que a solicitação nomeou, sendo a mais recente dessas respostas para uma Release a que conta. A validação mantém o que encontrou: assim que nenhuma build informa mais a falha — a próxima execução publica a camada sem ela, a próxima resposta de build, prévia ou grafo para essa Release é qualquer outra coisa, ou um cliente se conecta sem ter recebido tal resposta 1004 —, a entrada própria do documento volta a ser informada, e onde nenhuma build foi executada nada é omitido. Uma entrada aggrega posicionada em uma chave onde não há nenhuma recusa de build permanece, mesmo quando nomeia a mesma condição, porque pode ser uma segunda falha desse tipo que a build não informou.

code é um código estável e comparável por máquina para o que a entrada informa, de modo que um cliente pode ramificar com base nele sem comparar o texto da mensagem. Uma única chave traz o código, seja quem for que o atribuiu, e source diz qual tipo você tem em mãos, porque as camadas nomeiam as coisas a partir de vocabulários diferentes.

  • Em uma entrada aggrega — uma constatação sobre os documentos escritos — o código é a string sob a qual a condição está registrada, escrita como o pacote declarante seguido da regra em kebab-case. É o mesmo valor que um consumidor Go lê com CodeOf, cuja forma e superfície comparável são descritas na referência de sentinelas de erro.
  • Em uma entrada aggrega-build — um aviso que uma build gerou — o código é o que o ponto que o gerou atribuiu, e esta camada traz avisos de dois vocabulários diferentes, porque uma build gera avisos sobre dois tipos diferentes de coisa. Um aviso sobre a forma da topologia implantada traz um código de classe, como unsupported-field, atribuído onde quer que tenha sido gerado, seja um plugin de renderização ou a própria renderização; um código de classe nomeia uma classe de aviso em vez de uma condição registrada, então não tem linha na referência de sentinelas, e a referência de alertas descreve a classe unsupported-field e a flag que a silencia. Um aviso sobre os documentos escritos — um nome a uma edição de distância de um declarado, um parâmetro que nada lê — traz a string sob a qual sua condição está registrada, na mesma forma que uma entrada aggrega e com uma linha na referência de sentinelas. De qualquer forma, o código nomeia o que a constatação é, e não quem a encontrou, então uma única classe chega até você sob um único código, por mais lugares que a gerem, e ler o código em vez da camada é o que lhe diz qual dos dois você tem em mãos. A recusa em que uma build parou durante a renderização é a única entrada aqui que não é um aviso, e ela traz da mesma forma a string sob a qual sua condição está registrada.
  • Em uma entrada aggrega-lint — uma constatação sobre as 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 nomeia nenhuma regra — que um linter seu pode informar sob um código próprio —, esse código. É o identificador que aggrega lint imprime na linha da constatação, depois do código curto quando houver um, e o valor que aggrega lint --output json traz para essa mesma constatação, como ruleId, ou como code para uma constatação que não nomeia nenhuma regra. Uma constatação mantém uma única identidade entre as interfaces, então 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 o Aggrega declara está registrada como condição sob essa identidade, então está listada na tabela de todas as condições sob o código curto que aggrega lint imprime no início da linha da mesma constatação e que aggrega lint --output json traz nela como shortCode. Uma regra de um linter seu que o Aggrega não declara não nomeia nenhuma condição registrada, e tampouco uma constatação que não nomeia nenhuma regra, mesmo quando seu próprio código reproduz a identidade de uma regra que o Aggrega declara — então nenhuma das duas está listada ali. As regras são descritas na referência de aggrega lint.

Seja qual for a camada, a chave responde a uma única pergunta — o que é isto, em termos que uma máquina pode comparar —, então uma extensão de editor que destaca, agrupa ou suprime uma classe de constatações se baseia no código e continua funcionando quando a redação de uma mensagem muda.

Observe qual objeto traz o quê: isto é uma string em uma entrada de diagnóstico, distinta do code numérico em um envelope de erro JSON-RPC descrito abaixo em Códigos de erro. Uma resposta traz um ou outro, nunca ambos no mesmo lugar.

A chave é omitida quando nada do que produziu a entrada atribuiu um código, e todo tipo tem esse caso. Um buffer que nenhum parser de YAML consegue ler informa o próprio texto do parser e nenhum código, porque nenhuma condição própria do Aggrega está por trás dele; uma etapa que informa uma falha sem nomear uma condição também não tem nenhuma a informar; e um aviso ao qual quem o gerou não atribuiu nenhum código chega sem ele. Então trate code como opcional, da mesma forma que end_line e end_column, e ramifique com base nele apenas quando estiver presente. Um código é o que um diagnóstico informa e nunca o que seleciona um: nenhuma solicitação aceita um código, e escrever um de volta no seu próprio código lhe dá uma string em vez de uma forma de comparar.

O identificador que um programa compara e o que uma pessoa cita

Uma condição traz dois identificadores, e eles são para dois leitores diferentes. code é o de cima: qualificado e com hífens, de modo que um programa que ramifica com base nele se lê como o que significa. shortCode é a letra E seguida de quatro dígitos — E0164 — e é o que uma pessoa pode ler em voz alta, digitar em uma caixa de busca ou colar em uma issue. Ambos nomeiam a mesma condição e nenhum é abreviação do outro.

Qual usar depende de quem está lendo. Compare com code na sua extensão; mostre shortCode ao 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 comparando um número que não diz nada sobre a condição. Essa divisão é o motivo pelo qual os dois trafegam, e não apenas um.

codeDescription é onde a condição é publicada, trazido como { "href": … }, que é a estrutura própria do protocolo para uma referência a ser aberta para saber mais sobre um diagnóstico. Um editor que conhece o protocolo a transforma em uma opção “saiba mais” sem precisar aprender nada sobre o Aggrega, e nenhum cliente precisa de uma cópia das explicações. O endereço leva à lista publicada de todas as condições, onde a entrada de um shortCode nomeia a condição e continua com o passo a passo da correção na autoria.

O texto explicativo em si não está na entrada, e isso é proposital. Um diagnóstico é emitido a cada edição, então uma explicação que viajasse com cada um republicaria os mesmos parágrafos a cada tecla pressionada para um leitor que geralmente já os leu. Um cliente que quer o texto o pede uma vez, com aggrega/explainError abaixo; um cliente que pode seguir um link não precisa de nenhum dos dois.

As duas chaves estão presentes exatamente quando a entrada nomeia uma condição registrada, e ausentes juntas caso contrário. O que as decide é o que está por trás da entrada, e não qual camada a publicou, então leia as chaves, e não a camada:

  • Uma entrada que nomeia uma condição registrada traz as três. shortCode é resolvido, e a referência leva à lista em que ele é resolvido.
  • Uma entrada cujo código nomeia uma classe traz apenas code. A classe de um aviso de renderização e a identidade de uma constatação de convenções vinda de um linter seu — uma regra que o Aggrega não declara, ou o código que uma constatação que não nomeia nenhuma regra traz — são identificadores reais pelos quais você pode agrupar e suprimir, e nenhum dos dois é uma condição registrada — então não há número a citar nem nada no endereço que os descreva. Uma referência enviada mesmo assim seria um link que abre uma página que não trata do problema do leitor, e é por isso que nenhuma é enviada. Essa é a forma comum na camada aggrega-build, embora um aviso de build que de fato nomeia uma condição registrada traga as três como qualquer outro. Na camada aggrega-lint, a forma comum é o conjunto completo: uma regra do conjunto de regras do linter de publicação que o Aggrega declara é uma condição registrada, então sua constatação traz o mesmo shortCode que aggrega lint imprime no início da linha da constatação, e a referência ao lado.
  • Uma entrada que não nomeia nada não traz nenhum identificador.

Assim, os três casos se distinguem apenas pelas chaves: nenhum code significa nada a nomear, um code sem shortCode ao lado significa um identificador que não se resolve além disso, e o conjunto completo significa um identificador com um lugar onde ler sobre ele. Trate as duas novas chaves como opcionais, da mesma forma que code, e ofereça ao leitor algo para abrir apenas onde codeDescription tiver chegado.

Expandir um código que um diagnóstico trazia

aggrega/explainError transforma qualquer um dos identificadores de uma condição no que o compilador declara sobre ela e nas entradas publicadas que ensinam a correção na autoria. É a mesma expansão que aggrega explain realiza em um terminal e que a ferramenta explain-error realiza para um assistente, e os três respondem a partir de um único lugar, então um código expandido aqui e o mesmo código expandido lá são uma única resposta, e não três que por acaso coincidem.

code é obrigatório e aceita qualquer um dos identificadores — o shortCode que um diagnóstico trazia, ou o code ao lado dele —, porque um cliente que tem um deles não tem como obter o outro sem perguntar. Um valor vazio é recusado indicando o que enviar.

A resposta sempre traz shortCode, code e message: os dois identificadores da condição e a frase com que começa todo diagnóstico que a nomeia. Eles são declarados dentro do binário, então chegam sem rede e sem cache, e é isso que permite responder mesmo a um workspace que não contém nenhuma documentação. reference é o mesmo endereço que o codeDescription de um diagnóstico traz, para um cliente que prefere enviar seu leitor à documentação em vez de exibir o texto.

entries traz o passo a passo publicado, cada entrada como o heading que a abre e o body abaixo dele, na ordem em que a própria documentação os associa à condição. Ele é omitido quando o passo a passo não pôde ser adicionado, e note diz então por quê: a página publicada ainda não documenta nenhuma entrada para esta condição, ou este workspace não consegue ler a documentação — a máquina não tem nenhuma cópia, ou só uma que a verificação de assinaturas do workspace recusa. De qualquer forma, a condição acima continua valendo — a resposta não é uma falha, e um cliente mostra o que chegou com a nota ao lado. entries e note nunca chegam juntos.

Um código que nada resolve é recusado em vez de ser respondido com uma condição cujos campos estão todos vazios, e cada recusa diz de qual caso se trata: um código sob o qual nenhuma condição está registrada, um número que já nomeou uma condição e nunca nomeia outra, ou um código que este binário não declara quando a lista publicada não pôde ser lida de forma alguma — este último deixa as duas correções em aberto, pois uma lista publicada para uma versão diferente pode nomear uma condição que este binário não declara.

A documentação é lida do pacote armazenado em cache para o workspace que a solicitação nomeia, adquirido no primeiro uso quando está ausente, que é a única coisa para a qual esta solicitação alcança um registry — veja Alcançar um registry e gravar. Nada é gravado no workspace. Nenhuma validação o aciona: uma expansão acontece porque uma solicitação a pediu, então um registry nunca é alcançado enquanto um documento está sendo validado ou inspecionado.

Convenções de publicação, sob demanda e a cada edição

O daemon responde a duas perguntas diferentes sobre uma entidade do catálogo, e são as perguntas que aggrega validate e aggrega lint respondem no terminal: se o deployment está correto e se a entidade é publicável segundo as convenções do catálogo. Uma validação sempre responde à primeira. Ela responde à segunda somente quando você pede.

aggrega/lint pede isso explicitamente. Envie entity para uma única entidade do catálogo, release para cada entidade que o fechamento de dependências daquela Release alcança, ou nenhum dos dois para verificar cada entidade nos diretórios de catálogo configurados: os três escopos que o comando tem. Enviar entity e release ao mesmo tempo nomeia dois sujeitos diferentes e é recusado. A resposta traz checked, o número de documentos de entidade que a execução cobriu, e files, os achados agrupados pelo documento a que cada um se refere e ordenados por caminho, com as entradas de cada arquivo na forma de diagnóstico descrita acima. halted diz se o próprio veredito da execução recusa a publicação.

Não enviar nenhum dos dois verifica o catálogo inteiro da forma como aggrega lint faz sem argumento. Um workspace cuja configuração não informa diretórios de catálogo de Release próprios é verificado uma vez, sobre os próprios diretórios, e a resposta é a descrita acima. Um workspace que nomeia Releases em workspace.releases é verificado uma vez para cada Release nele, sobre os diretórios que aquela Release lê, e nunca sobre todos juntos; assim, variantes de catálogo mantidas lado a lado, uma por Release, são verificadas cada uma nos termos da Release que as lê. A resposta traz então também passes, uma entrada por passada: releases, as Releases para as quais ela foi executada, cada uma relativa à raiz do workspace, com Releases que leem os mesmos diretórios compartilhando uma entrada; catalogDirs, os diretórios que ela leu, escritos como files escreve um caminho, e vazio para uma Release que não lê nenhum, o que é informado em vez de fazer as outras falharem; e as contagens e os files próprios daquela passada, que são o que diz para qual Release um achado foi encontrado. checked, as contagens e files em torno deles cobrem todas as passadas juntas, de modo que um cliente que não lê passes ainda lê a execução inteira. Uma execução em que nenhuma passada tem um diretório para ler é recusada em vez de ser respondida como um catálogo limpo.

Defina prePublish junto com entity para comparar essa entidade com a versão publicada anteriormente e classificar em relação a ela o incremento de versão proposto. Esse é o único modo aqui que alcança um registry, e ele é executado porque a solicitação o nomeou: o que admite uma operação que vai para fora é que um chamador a tenha pedido. Ele só faz sentido com entity, então prePublish sem entidade é recusado.

aggrega/lint não publica nada na sessão. Ele responde sobre o sujeito que recebeu, e escrever seus achados na lista de problemas do editor substituiria o que uma validação publicou para arquivos que a solicitação nunca cobriu. Nada é gravado em disco em nenhum modo.

serve.lint_on_validate executa as mesmas regras a cada validação, e fica desativado a menos que você o ative. Ative-o em .aggrega-config.yaml, no workspace sobre cujas entidades você quer a orientação:

serve:
lint_on_validate: true

Não existe flag para isso, porque a pergunta que ele responde trata do conteúdo do próprio workspace, e quem tem essa pergunta é a pessoa que escreve o workspace, e não quem iniciou o daemon. Com ele ativado, uma validação de uma entidade do catálogo também publica os achados sobre convenções sob a fonte aggrega-lint; com ele desativado, o padrão, uma validação informa apenas as camadas de correção e nenhum achado sobre convenções chega até você. Uma sessão do editor não diz nada sobre se uma entidade é publicável até que você peça essa camada.

Três coisas valem nessa camada, não importa o que a chave diga. Somente o modo que lê conteúdo local é executado, então nenhum registry é consultado, nada é baixado e nada é gravado; a comparação pré-publicação é alcançada enviando aggrega/lint com prePublish, nunca por uma validação, porque uma verificação executada a cada edição é exatamente onde um registry não deve ser alcançado. As regras são avaliadas sobre o buffer que a solicitação trouxe, e não sobre o arquivo em disco, de modo que um nome que você corrige deixa de ser informado antes de você salvar. E os achados são consultivos: um documento que os gera ainda é validado, e sua Release ainda é resolvida e renderizada; portanto, isso acrescenta uma camada e nunca uma recusa.

A chave controla essa camada e nada mais. aggrega/lint responde ao que for perguntado com qualquer um dos valores, porque um chamador que o envia pediu a verificação pelo nome.

Somente os tipos que são publicados em um catálogo são verificados, porque é disso que tratam as convenções. Documentos que não são conteúdo de catálogo, entre eles um Aggregate e uma Release, são ignorados, assim como YAML que não é de forma alguma um documento do Aggrega. É isso que mantém uma sessão em silêncio sobre os documentos em que um autor passa a maior parte do tempo.

Como um caminho informado é escrito

Quando uma resposta nomeia um documento que o daemon localizou para você, uma única regra decide como esse caminho é escrito: relativo à raiz do workspace quando o documento está dentro dela, e o caminho absoluto quando não está. Isso abrange o file de uma identidade de entidade, o file de uma definição de entidade e o file pelo qual cada grupo é indexado em uma resposta de lint. Ambas as formas são caminhos que você pode abrir, a primeira em relação à raiz que você indicou, a segunda como está, e nenhuma delas é deixada vazia por causa de onde o documento fica.

A segunda metade da regra é o que um diretório de catálogo configurado precisa. Um workspace pode apontar para diretórios de catálogo em qualquer lugar da máquina, e um documento em um deles é tão real quanto um documento sob a raiz. O caminho absoluto é o que o nomeia, e é a mesma forma que aggrega lint e um diagnóstico de interrupção imprimem para esse arquivo em um terminal; assim, um arquivo tem um único nome, qualquer que seja a superfície que você consultou. O que você não vai receber é um caminho que sobe acima da raiz, que nomearia arquivos diferentes dependendo de onde fosse lido.

Qual forma você recebeu pode ser lido no valor: tudo o que sua plataforma lê como caminho absoluto é a segunda forma, e todo o resto é relativo à raiz do workspace. Você não precisa testar isso para abrir o arquivo (juntar um caminho relativo à raiz e abrir um absoluto como está funcionam ambos), mas um cliente que agrupa por documento do workspace pode distinguir os dois sem perguntar.

O que esta regra não abrange. Um caminho que você envia é regido pelo contrato próprio daquela solicitação, informado com a solicitação acima e geralmente mais rigoroso: um destino é recusado a menos que seja relativo à raiz do workspace e se resolva dentro dela, links incluídos. A notificação aggrega/publishDiagnostics traz seu file em forma absoluta em todos os casos, dentro e fora da raiz, porque esse valor é o identificador que você compara com seus próprios documentos abertos, e não uma coordenada no workspace: seu editor o resolve como um caminho do sistema de arquivos. aggrega/releaseCandidates e aggrega/activeRelease nomeiam cada Release e cada lockfile pelo caminho absoluto, como dizem suas próprias entradas acima. E aggrega/irGraph traz o grafo compilado como o compilador o registrou, retendo apenas os valores que um autor declarou sensíveis, de modo que qualquer caminho registrado dentro dele é o que o compilador registrou, na forma que o próprio contrato do grafo fixa, e não um que este protocolo compôs para você.

Quais formas um parâmetro que você envia aceita

O que um caminho nomeia, e não qual método o transporta, decide quais formas esse parâmetro aceita. A entrada própria de cada solicitação acima informa o contrato dos parâmetros que ela aceita; o que segue é o contraste entre elas, e por que é um contraste, e não uma inconsistência que você precise memorizar método a método.

Um parâmetro que nomeia um documento que você já tem pode ser escrito de três maneiras: relativo à raiz do workspace, absoluto ou como o endereço file:// que um cliente de language server envia para um documento aberto. Esse é o file ou 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 nomeiam um mesmo documento e recebem a mesma resposta, porque cada uma é reduzida a uma única forma canônica no limite da solicitação antes que qualquer coisa a leia; assim, um documento que você validou pelo caminho é encontrado pelo endereço, e vice-versa, e a forma que você envia não muda nada na resposta. Um endereço é lido como o caminho que nomeia, com os escapes percentuais decodificados, quando sua autoridade está vazia ou é localhost; um que nomeia outra máquina é lido como o compartilhamento de rede dessa máquina em um sistema que abre um documento ali dessa forma, e não nomeia nada que o daemon possa abrir em outro lugar. Um endereço que também traz uma query, um fragmento, credenciais ou uma porta também não nomeia nada que o daemon possa abrir. Um valor que não começa com file://, seja qual for o uso de maiúsculas e minúsculas, nunca é lido como endereço, e a recusa de arquivo não validado nomeia o valor que você enviou, qualquer que tenha sido a forma. Desses, aggrega/insertionPoint e aggrega/connectionAtPosition são os dois que leem o documento do disco quando você não tem uma cópia dele, e eles respondem apenas para um documento dentro do workspace: um fora da raiz (como escrito, ou por meio de um link que sai dela, para o arquivo ou para um diretório no caminho) é recusado qualquer que seja a das três formas que o nomeie, e um documento dentro da raiz é respondido nas três. Os outros oito não leem nada do disco no caminho que nomeiam (aggrega/validate obtém os bytes do documento de content, e os demais respondem a partir do que foi validado), então respondem para um documento onde quer que você o tenha, dentro do workspace ou não, e nenhum link que nomeiam é seguido para ler um arquivo. Um parâmetro que nomeia um documento que você selecionou fora do workspace é o mesmo caso pelo mesmo motivo: o source de aggrega/import é lido onde realmente está, como diz sua própria entrada. Ambos são exceções ao limite do workspace por classe (um documento que o cliente mantém aberto e um arquivo que uma pessoa escolheu), e O limite do workspace explica por que cada um é uma exceção.

Um parâmetro pelo qual o daemon precisa localizar um documento dentro do workspace aceita um caminho relativo ao workspace e nada mais. release é o que você precisa conhecer (em aggrega/irGraph, e sob o mesmo contrato onde mais aparecer), e um valor absoluto é recusado com o erro invalid-params, que informa o contrato e depois nomeia a falha específica. As solicitações que gravam dentro do workspace submetem seus destinos a esse mesmo contrato, como diz a entrada própria de cada uma. Cada um desses caminhos é então julgado por aonde leva, por uma única regra, quer a solicitação o leia, quer o grave (a definição de dentro que O limite do workspace informa), e um caminho que leva para fora é recusado com o erro próprio daquela solicitação, citando o valor como você o enviou, sem nada lido ou gravado: tanto um link para um arquivo fora quanto um link para um diretório no caminho, e também um caminho ainda não criado sob um diretório vinculado que leva para fora, que é recusado por causa do link em vez de ser gravado, ou procurado fora e informado como ausente. Isso abrange cada caminho que uma solicitação nomeia para o daemon ler (release onde quer que apareça, o entity de aggrega/lint, e entity, plugin, file e from das solicitações de publicação), de modo que uma solicitação não pode ler por meio de um link um arquivo que as próprias listagens do workspace deixam de fora, e cada destino: os diretórios em que uma geração, uma importação e uma build gravam, a entidade ao lado da qual aggrega/pin grava seu lock, o arquivo de entidade e o módulo que aggrega/pluginSync lê e reescreve, e o documento que aggrega/editDocument edita. Um release que nomeia uma Release que a configuração do seu workspace nomeia é a única exceção, como diz a entrada de aggrega/irGraph.

Os dois diferem porque as falhas diferem. Um parâmetro que nomeia um documento que você já tem deixa uma única pergunta, qual documento, então reduzir sua forma à canônica não perde nada, e aceitar cada uma também não custa nada a você. Um parâmetro que seleciona um documento de dentro do workspace não está nessa posição: nas bibliotecas de caminhos que um cliente provavelmente usa, juntar um valor absoluto a uma raiz produz esse valor absoluto em vez de um erro. Assim, um valor consertado silenciosamente faria o daemon ler (e informar achados sobre) um caminho que o workspace nunca conteve, e você seria informado sobre um arquivo que não existe. Recusar é a resposta, em vez de consertar, porque um daemon que consertasse um valor assim deixaria cada cliente que envia um acreditando que o contrato é opcional.

Como uma entidade é endereçada

Cada entidade que uma resposta nomeia é endereçada da mesma forma: kind, name e file. Faça o join por essas três com aggrega/catalogIndex para qualquer coisa que você queira exibir: é a superfície que traz o conjunto descritivo completo de uma entidade (apiVersion, description e labels), de modo que uma resposta que só precisa nomear uma entidade informa as três chaves de endereçamento e deixa a descrição em um único lugar. Uma consulta por nome como aggrega/entityDefinition repete os poucos campos descritivos de que trata sua própria resposta; o índice continua sendo a superfície com a qual fazer o join quando você quer o conjunto.

Onde uma resposta pode nomear entidades de mais de um lugar, cada identidade traz origin ao lado dessas três chaves. aggrega/catalogIndex e aggrega/attachCandidates fazem isso, porque suas entidades vêm dos documentos do workspace e dos diretórios de catálogo configurados. Uma resposta que se baseia em um único lugar informa apenas as três chaves e nenhum origin, já que uma chave com um único valor possível não diz nada a você: cada entidade que uma resposta assim nomeia é um documento do workspace, e seu file é um caminho relativo ao workspace que você pode abrir. Então leia origin onde ele estiver presente, em vez de exigi-lo em todo lugar; as três chaves são aquilo pelo qual você faz o join de qualquer forma.

origin pertence a uma resposta que lista entidades, em que distinguir as populações é problema do leitor. Uma resposta por nome como aggrega/entityDefinition não traz nenhum: ela nomeia a única entidade para a qual o nome foi resolvido, então não há populações a separar. O próprio item dela acima diz quando seu file fica vazio; não interprete esse vazio pelos 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 do Aggrega sob a raiz do workspace. file é seu caminho relativo a essa raiz, que é um caminho que seu cliente pode abrir.
  • catalog — uma entidade resolvida a partir dos diretórios de catálogo configurados. file fica vazio nesta listagem, e o name é o endereço inteiro. Ele fica vazio porque a listagem informa o que a consulta ao catálogo enumerou, que é uma identidade e não um documento, então a entrada não tem nenhum caminho a informar; não se trata de um caminho retido por causa de onde fica. Peça a aggrega/entityDefinition o mesmo nome quando quiser o documento: essa solicitação resolve a entidade e informa seu file segundo a regra acima, de modo que um diretório de catálogo fora da raiz do workspace é nomeado ali pelo caminho absoluto. name é, de qualquer forma, a coordenada que um Aggregate, uma Recipe e a consulta ao catálogo usam.

Leia os dois juntos em vez de testar apenas file. Um file vazio por si só não poderia dizer a você se a entidade não tem caminho no workspace ou se simplesmente nenhum foi informado; origin responde a isso diretamente.

Onde uma Feature é alcançável das duas formas (a raiz do workspace é ela mesma um dos diretórios de catálogo configurados, o que é um layout comum), ela é informada uma vez, como o documento do workspace, porque essa é a cópia cujo arquivo você pode abrir.

O que uma resposta de attach-candidate diz a você

aggrega/attachCandidates responde a uma única pergunta (quais Features este conjunto de labels admite) e oferece três maneiras de dizer a qual conjunto de labels você se refere. Envie exatamente uma coordenada; enviar duas, ou nenhuma, é recusado em vez de classificado.

{node} endereça um documento do workspace pelo seu metadata.name e não precisa de mais nada. A correspondência é avaliada em relação aos labels que esse documento declara em metadata.labels, e a resposta informa labelSource: "declared".

{graphNode, release} endereça um nó em um grafo compilado. graphNode é o id sob o qual o grafo indexa o nó: o mesmo id que você lê de aggrega/irGraph, incluindo a forma qualificada que um nó fornecido por um subagregado traz. release é um caminho relativo à raiz do workspace que nomeia a Release cujo grafo deve ser construído, o mesmo valor que aggrega/irGraph aceita. A correspondência é avaliada em relação aos labels finalizados do nó, e a resposta informa labelSource: "resolved".

{labels} traz o próprio conjunto de labels e não endereça nada. É a forma subjacente às outras duas: a correspondência é uma função de um conjunto de labels e das Features disponíveis, de modo que um cliente que já tem um conjunto de labels não tem nada a nomear e nada a esperar. Envie um objeto JSON de pares de labels; a resposta informa labelSource: "supplied" e um node vazio, porque esta solicitação não endereçou nenhum. Um objeto vazio é uma coordenada (pergunta sobre um nó sem nenhum label), enquanto omitir a chave por completo, ou enviar null, não endereça nada e é recusado.

As duas coordenadas por nome são separadas porque 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 string e nomear coisas diferentes, de modo que um único parâmetro que trouxesse ambos seria ambíguo, e um daemon que adivinhasse qual espaço você quis dizer às vezes responderia com segurança sobre o sujeito errado. Dizer qual pergunta você está fazendo é o que elimina a ambiguidade.

labelSource diz a você até onde a resposta vai, e os três valores não são intercambiáveis. declared é uma correspondência sobre o que um documento diz de si mesmo, que é o que uma leitura do código-fonte consegue ver. resolved é uma correspondência sobre os labels com que o nó de fato termina, que é aquilo em relação ao qual uma build avalia a aplicabilidade; portanto, uma resposta resolved é uma afirmação sobre o que uma build decidiria, e uma resposta declared não é. supplied diz que o daemon não leu nenhum label e comparou o que você enviou; quão sólida essa resposta é depende inteiramente de onde veio seu conjunto de labels.

É por isso que um cliente que tem um grafo deve enviar {labels} em vez de um nome. Os labels finalizados de um nó são os labels do tipo de componente para o qual ele se resolve, e não os de um documento que por acaso compartilha seu id, e um attachment label-transform pode depois acrescentar, alterar ou remover labels; portanto, os labels que decidem a aplicabilidade de um nó não precisam ser os 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 obtê-la. Devolva um conjunto que o próprio daemon informou (o de um nó a partir de aggrega/irGraph, o de uma entidade a partir de aggrega/catalogIndex) e sua ideia dos labels de um nó não pode divergir da do daemon, porque o conjunto nunca saiu da própria resposta dele. Se você montar um por conta própria, estará fazendo uma pergunta hipotética, que é respondida honestamente e não é uma afirmação sobre nenhum nó que o workspace contém.

Os candidatos vêm do workspace e do catálogo. Um workspace que mantém suas Features em um catálogo em vez de na própria árvore não tem nenhuma Feature local, e 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 os diretórios de catálogo que a configuração do workspace atribui a essa Release declaram, e os documentos próprios do workspace são oferecidos exceto os que estão sob um diretório de catálogo que apenas outras Releases leem. Assim, um workspace que mantém uma variante de uma Feature por Release oferece ao grafo de cada Release a 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 nomeiam nenhuma Release, então se baseiam em cada documento do workspace e nos catalog_dirs do próprio workspace. Uma Feature que não declara nenhuma aplicabilidade é candidata para cada nó (uma declaração ausente não impõe 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 deixaria um erro de digitação ampliar o que você oferece.

Um nome que não se 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 possa ser anexado a ele, e informar assim um nome digitado errado apresentaria um erro de digitação como uma resposta definitiva. A recusa nomeia o espaço em que procurou, para que você saiba se deve procurar um documento do workspace ou um nó do grafo. {labels} não tem esse risco (não há nome para digitar errado), então um conjunto de labels que nada admite volta como uma resposta bem-sucedida trazendo um array vazio, e uma solicitação que o daemon não consegue ler ainda é recusada antes que qualquer correspondência seja 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, então esse caminho recusa com o erro de lockfile ausente quando nenhum foi gerado, nomeando o comando a executar: a mesma pré-condição que aggrega/irGraph tem, pelo mesmo motivo. Endereçar um documento do workspace não constrói nenhum grafo, e fornecer um conjunto de labels não constrói nada, então ambas respondem em um workspace que ninguém preparou ainda.

Ela informa e nunca cria. O método não altera nada, não grava nada e não cria nenhum attachment. Compor e aplicar qualquer edição cabe ao editor, que é onde estão o buffer e o histórico de desfazer.

O que ela resolve depende da coordenada, e as três não são iguais. {node} não resolve nada e não alcança nenhum registry nem a rede: os candidatos vêm do workspace e dos diretórios de catálogo, ambos já em disco. {labels} resolve ainda menos: não consulta nada, porque não há nada a consultar. {graphNode, release} constrói o grafo da Release, então resolve o fechamento de dependências dessa Release da mesma forma que aggrega/irGraph: primeiro a partir dos diretórios de catálogo locais e do cache de artefatos, e a partir do registry configurado para uma entidade que nenhum dos dois contém. As três respondem offline para um workspace cujas entidades são todas locais; somente a coordenada de nó do grafo pode ir procurar mais longe.

Perguntando sobre uma conexão

Uma conexão que um componente traça pode trazer attachments próprios, preenchendo os slots que seu socket declara no Component consumidor: por exemplo, uma credencial que o componente apresenta ao que quer que a conexão alcance. Envie connection ao lado de {graphNode, release} para perguntar o que pode ir ali: socket é o socket de dependência pelo qual a conexão é ligada e alias o nome que ela traz dentro desse socket, ambos exatamente como o autor os escreveu. Uma conexão existe apenas em um grafo compilado, então connection ao lado de node ou labels é recusado, assim como uma conexão que não nomeia nenhum socket ou nenhum alias, ou uma que o nó não traça.

A resposta é a resposta de nó do grafo mais os slots da conexão. candidates mantém seu significado (as Features que podem ser anexadas ao próprio nó) e slots é acrescentado, uma entrada por slot que o socket declara, na ordem em que o Component os declara:

  • slot — o nome sob o qual um attachment que o preenche é escrito nos features da conexão.
  • selector, required, inject, sensitive e description — o slot exatamente como o Component o declara no socket, vazio ou false onde não declara nada. selector é a restrição pela qual os candidatos foram filtrados, de modo que você pode explicar um candidato, ou sua ausência, apenas a partir da resposta.
  • candidates — as Features que podem preencher este slot nesta conexão. Uma build submete um attachment assim a duas regras, e ambas são aplicadas: a aplicabilidade declarada da Feature em relação aos labels finalizados do nó, à qual todo attachment que o nó traz está sujeito, e o selector do slot em relação aos labels próprios da Feature. Portanto, os candidatos de um slot estão sempre entre os do nó, filtrados pelo seletor. Uma Feature cujos labels o seletor não consegue avaliar não é oferecida, porque uma build a recusa em vez de admiti-la.

Onde nenhum slot pode ser preenchido, slots é uma lista vazia e noSlotReason diz por quê. Leia o motivo em vez de tomar uma lista vazia por “nenhuma Feature correspondeu”: essa seria uma resposta diferente, e o motivo é o que distingue as duas:

  • feature-created-connection — uma Feature traçou a conexão, a partir do próprio bloco de dependências. Um attachment só é escrito em uma conexão que um componente ou a Release traça, então nada vai aqui, não importa o que o socket declare.
  • ad-hoc-socket — o socket é um que o Component não declara. O autor o nomeou, o que é permitido, e um socket não declarado não declara nenhum slot.
  • no-slot-declared — o Component declara o socket sem nenhum slot.

noSlotReason fica ausente sempre que existe um slot, e slots e noSlotReason ficam ambos ausentes da resposta a uma solicitação que não nomeou nenhuma conexão; assim, uma solicitação que não nomeia nenhuma conexão é respondida sem nenhum dos dois campos.

document é aceito e não muda nada aqui. Os slots são os do socket e os candidatos os das Features, os mesmos em qualquer documento em que um attachment seja escrito; para onde ele vai é a resposta de aggrega/attachmentContainer. Um valor diferente de aggregate ou release ainda é recusado, porque um valor aceito e ignorado parece a quem o envia um valor que foi respeitado.

O que uma resposta de connection-candidate diz a você

aggrega/connectionCandidates responde a duas perguntas ao mesmo tempo, e apenas uma delas tem uma resposta completa. Ler a resposta como uma única lista filtrada leva a entender errado a outra.

Cada socket informado traz targets (os Components locais do workspace cujos labels declarados satisfazem a restrição de labels que esse socket declara sobre o que pode satisfazê-lo), mais o selector a partir do qual esses destinos foram calculados, o flag required que o socket declara e declaration. targets é sempre um array, vazio em vez de ausente, de modo que um socket que nada satisfaz ainda é informado como um socket que a entidade declara.

A metade dos destinos é completa. O conjunto é decidido avaliando a restrição declarada do socket em relação aos labels declarados de um candidato, a mesma avaliação que uma build faz, de modo que o que você oferece é o que a mesma restrição admite durante uma build. Um socket que não declara nenhuma restrição deixa seus destinos sem restrição e informa cada Component: esse é o significado que a linguagem de restrições dá a um seletor vazio, não um erro.

A metade dos sockets é aberta, e declaration mais adHocSocketsAccepted são como você sabe disso. O autor de um Aggregate é dono da topologia dele e pode ligar um socket que a entidade de catálogo do componente nunca declarou, então os sockets que uma entidade declara são um conjunto inicial útil e não o conjunto de nomes de socket válidos. Apresente-os como sugestões, não como as únicas opções: um seletor de interface que oferecesse apenas os sockets declarados diria ao autor que a liberdade dele é mais estreita do que é.

  • declaration é declared quando a entidade endereçada lista o socket em seu usesSchema, e ad-hoc quando não lista. São os mesmos dois valores que uma aresta traz no grafo IR, de modo que um único vocabulário responde “de onde veio este socket” onde quer que você encontre a pergunta.
  • adHocSocketsAccepted informa se a superfície da entidade endereçada aceita um socket que a própria declaração dela não lista. Isso não é sempre verdadeiro: a superfície de dependências de um Component aceita um, e a superfície de attachment de uma Feature não, porque um attachment participa da topologia que a Feature anexada declara em vez de criar a sua própria. Um socket ad hoc em uma superfície que não aceita nenhum é informado sem destinos, porque nenhuma conexão por ele seria construída.

Nomear um socket na solicitação limita a resposta a esse único socket, e essa é a única forma de perguntar sobre 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 cada socket que a entidade declara, na ordem em que foram escritos.

O que ela informa é uma correspondência sobre labels declarados. Uma build avalia a restrição de um socket em relação aos labels finalizados do nó na outra ponta da aresta, e esses são os labels do tipo de componente para o qual esse nó se resolve, depois que qualquer attachment label-transform tenha agido, e não necessariamente os labels do documento que você nomeou. Portanto, uma resposta positiva aqui não é uma promessa sobre o que uma build decidirá: é o mesmo limite que aggrega/attachCandidates tem com sua fonte de labels declared.

Ela informa e nunca cria. O método não resolve nada, não alcança nenhum registry nem a rede e não grava nada: não cria nenhuma aresta e não propõe nenhum texto. Compor e aplicar a edição cabe ao editor, que é onde estão o buffer e o histórico de desfazer.

Para as identidades de entidade em targets (kind, name e file), faça o join com aggrega/catalogIndex como descrito em Como uma entidade é endereçada. Os campos descritivos são informados ali e deliberadamente não repetidos aqui, de modo que esta resposta não traz uma segunda cópia deles que possa ficar dessincronizada. Os destinos são Components do workspace, então cada um tem um file que você pode abrir e nenhum traz um origin: esta resposta se baseia em um único lugar, e o join é pelas três chaves.

O que uma resposta de attachment-container diz a você

aggrega/attachmentContainer fica entre as solicitações de candidatos acima e o ponto de inserção abaixo. Aquelas dizem o que pode ser anexado a um nó; esta diz em qual contêiner um attachment para ele deve ir, e em qual documento; a seguinte diz em que ponto dos bytes desse documento o texto vai.

Peça o contêiner em vez de compô-lo. O id de um nó e o caminho do subsistema que o envolve são ambos escritos com pontos entre suas partes, e um ponto é um caractere válido em um nome que um autor digita; portanto, de fora do documento não há como distinguir um ponto estrutural de um que está dentro de um nome. Um cliente que montasse o caminho por conta própria produziria algo que parece correto e endereça uma chave que ninguém escreveu, e a edição seguinte criaria essa chave em vez de ser recusada. Foi o compilador que compôs os dois caminhos, então é o compilador que os decompõe.

Um id de nó não traz nenhum vestígio do subsistema que o envolve. Um componente escrito dentro de subsystems.billing.subsystems.payments é indexado no grafo como ledger, exatamente como seria um componente de nível superior, então não há nada no id com que um cliente possa trabalhar, por mais cuidadosamente que o divida.

A resposta tem três campos.

  • node repete o nó de que trata a resposta, de modo que um cliente com várias solicitações pendentes associa cada resposta à sua pergunta sem manter uma ordem própria.
  • file é o documento em que o nó foi escrito, relativo ao workspace. Ele faz parte da resposta em vez de ser algo que você já sabe: um nó fornecido por um módulo importado foi escrito no documento próprio desse módulo, com o nome que o módulo lhe deu, de modo que tanto o arquivo quanto o último segmento do contêiner diferem de qualquer coisa que a solicitação tenha nomeado.
  • container é o caminho estrutural a partir da raiz desse documento, como uma lista de segmentos: ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Cada nível de um subsistema envolvente fica novamente sob a chave subsystems, que é como o documento o escreve. Um componente que o autor escreveu no nível superior nomeia, em vez disso, ["spec", "components", "checkout", "features"], porque o escopo em que tal componente é compilado não é um que algum arquivo contenha.

É uma lista de segmentos e nunca uma string concatenada, e essa é a razão de ser da forma. Um caminho concatenado teria de ser dividido novamente por quem o recebesse, o que reintroduziria a ambiguidade acima uma chamada depois. Passe a lista sem alterações para aggrega/insertionPoint como seu container.

Ela lê estrutura e nunca significado. A resposta é derivada do documento em que o nó foi escrito, do escopo em que ele está e do nome que o autor digitou. Nada é extraído de como um componente se chama, de qual tipo ele traz ou do que algum label diz.

Ela informa e nunca grava. O método não altera nada e não grava nada em nenhum documento. Não cria nenhum attachment, não compõe texto e não aplica nenhuma edição; não decide o que pode ser anexado, o que cabe a aggrega/attachCandidates.

Uma solicitação que nomeia um nó que o grafo não contém é recusada em vez de respondida. Os ids de nó são as próprias chaves do grafo (leia-os do grafo que aggrega/irGraph retorna) e um nó fornecido por um módulo importado traz um id qualificado. Um nó para o qual o grafo não registra nenhum documento também é recusado: onde um attachment deve ir é um fato sobre um documento, então um nó sem documento não tem resposta, em vez de ter uma vazia.

Ela exige um lockfile, pelo mesmo motivo que aggrega/irGraph: nomear o contêiner significa construir o grafo da Release, e um grafo construído a partir de bytes que nada garante seria informado exatamente como um que foi verificado.

Um attachment em uma conexão

Envie connection ao lado de {graphNode, release} (com seu socket, seu alias e seu document) e a resposta nomeia o contêiner features na entrada própria dessa conexão em vez da do nó. document é obrigatório aqui, porque qualquer um dos dois documentos pode conter um attachment em uma conexão que o Aggregate traçou: o desenvolvedor escreve um na entrada da conexão no Aggregate, e o operador na entrada por aresta da Release correspondente.

  • aggregate nomeia 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 por nível como acima. Uma conexão que a Release traçou não tem entrada no Aggregate, então é recusada ali.
  • release nomeia a entrada por aresta sob a entrada própria 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. Onde ela não a escreve, aggrega/insertionPoint informa em missingContainerKeys as chaves que ainda faltam escrever. file é então o documento da Release. Uma Release que não escreve nenhuma entrada para o nó é recusada: onde o nó é posicionado cabe ao operador escrever, e a resposta não decide isso.

Uma conexão que uma Feature traçou é recusada em qualquer um dos dois documentos, pelo motivo 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 traça é recusada em vez de respondida com um caminho. Todas as outras propriedades acima continuam valendo: a resposta é uma lista de segmentos, lê estrutura e nunca significado, e não grava nada.

O que uma resposta de connection-at-position diz a você

aggrega/connectionAtPosition é o passo anterior às duas solicitações de conexão acima, para um cliente que tem um lugar em um documento em vez de um nó em um grafo: por exemplo, um cursor na entrada de uma conexão. Ela responde qual conexão está escrita ali, nas coordenadas que essas solicitações aceitam, e para por aí.

A resposta é uma de duas metades, nunca ambas.

  • graphNode e connection — o nó cujo componente traça a conexão, pelo id sob o qual o grafo compilado o indexa, e a conexão pelo seu socket e pelo seu alias, com document nomeando o documento em que a posição foi lida: aggregate para o Aggregate ou um módulo que ele importa, release para a Release. Passe graphNode, o mesmo release e connection para aggrega/attachCandidates para obter os slots que o socket da conexão declara, e para aggrega/attachmentContainer para saber onde vai um attachment nela; o contêiner que ele nomeia fica dentro da própria entrada em que a posição caiu.
  • noConnectionReason — por que nenhuma conexão é informada. O conjunto é fechado:
    • no-connection-entry — a posição não está em nenhuma entrada em que um attachment é escrito. Uma conexão escrita como lista de destinos (db: [store]) e uma que o próprio bloco de dependências de uma Feature traça não trazem tal entrada, então uma posição em qualquer uma delas também recebe essa resposta.
    • feature-created-connection — a posição está na entrada da Release para uma conexão que uma Feature traçou, que não traz nenhum attachment pelo motivo que a resposta sobre slots dá acima. Uma Release escreve tal entrada onde o bloco de dependências de uma Feature traça por um socket que o Component consumidor também declara; a entrada é construída quer não configure nada, quer defina o infra por aresta da conexão.
    • unknown-connection — a posição está em uma entrada que a Release escreve para uma conexão que o grafo compilado não contém. Uma Release que é construída pode conter uma: por exemplo, uma entrada sob um alias que nada traça e que não configura nada (sem target, sem infra, sem features), ou uma entrada para um componente que um interruptor active: desativou, cujas conexões saem da build junto com ele.

Quais entradas contam. No Aggregate, cada conexão que um componente traça, em sua entrada sob o alias da conexão no documento em que o componente foi escrito (para um componente fornecido por um módulo importado, o documento próprio desse módulo). Na Release, cada entrada por aresta que ela escreve, quer a entrada trace sua conexão, quer configure uma que o Aggregate traçou. Onde cada entrada fica é o que o grafo compilado registra, então se uma chave é uma conexão nunca é deduzido de como ela se chama. Um componente que um interruptor active: desativou não está no grafo compilado, então as próprias entradas dele no Aggregate respondem no-connection-entry, enquanto a entrada da Release para uma de suas conexões responde unknown-connection.

Uma posição em qualquer lugar dentro de uma entrada está dentro dela. A entrada vai da sua chave de alias até a última linha indentada sob ela, de modo que uma posição no alias, no seu target ou dentro dos seus features é respondida para essa conexão, e onde as entradas se aninham vence a mais interna. 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 ou vários, e o mesmo vale para uma posição na indentação antes de uma chave de alias.

Qual documento é qual decorre da Release. O arquivo próprio da Release é lido para as entradas que ela escreve; qualquer outro arquivo é lido para as entradas em que o grafo registra componentes como escritos. Um documento do qual o grafo da Release não lê nada responde no-connection-entry em todas as posições.

Ela informa e nunca grava, e lê o documento da mesma forma que aggrega/insertionPoint: primeiro a partir da cópia da sessão e, caso contrário, do disco, dentro do workspace, com as mesmas recusas para um documento que está fora dele, é ilegível ou não é YAML bem formado. Ela exige um lockfile, pelo motivo pelo qual aggrega/attachmentContainer exige, e constrói o grafo sem renderizar nada.

O que uma resposta de ponto de inserção diz a você

aggrega/insertionPoint é a contraparte das duas solicitações de candidatos acima. Aquelas dizem o que pode ser anexado ou conectado; esta diz onde o texto correspondente fica em um documento específico. Ela responde e para aí.

Você nomeia o contêiner; o daemon o localiza. container é um caminho estrutural a partir da raiz do documento — ["spec", "components", "web", "features"] — e é a sua declaração de onde uma entrada desse tipo fica em um documento desse tipo. O daemon não deriva esse caminho do nome de uma entidade, do tipo que ela carrega nem do que ela parece significar. Ele lê os bytes que o autor escreveu e informa quais segmentos do caminho este documento já tem, as colunas em que suas entradas estão e a última linha que seu bloco mais interno alcança. Assim, saber qual chave continua sendo tarefa de quem chama, e saber onde as entradas dessa chave ficam neste arquivo vem daqui.

Para anexar uma Feature a um nó de um grafo compilado, quem chama não precisa conhecer essa chave por conta própria: peça a aggrega/attachmentContainer o documento e o contêiner, e passe ambos aqui sem alteração.

A resposta é uma posição de largura zero mais o que você precisa escrever ao redor dela. file é o documento, relativo ao workspace. container repete o caminho sobre o qual você perguntou, de modo que um cliente com várias solicitações pendentes associa cada resposta à sua pergunta sem manter uma ordem própria. position insere em vez de substituir: nada que já esteja no documento é sobrescrito ou deslocado.

  • precededByLineBreak — comece o texto que você escreve com uma quebra de linha. A posição fica no fim da linha que a nova entrada segue, o que é válido quer o arquivo termine ou não com uma quebra de linha, e não altera nenhum byte já escrito. Ela só é false para um documento que não contém nada após o qual se posicionar, caso em que se escreve a partir do início do arquivo.
  • missingContainerKeys — os segmentos do caminho do contêiner que este documento ainda não contém, do mais externo para o mais interno. Cada um precisa ser escrito como uma chave própria antes que a entrada possa ir dentro do mais interno. Fica vazio quando o caminho inteiro 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 é recuado.
  • indentStepMeasured — se esse passo foi medido a partir do próprio aninhamento deste documento. Quando é false, o documento não apresenta aninhamento a medir e o passo é um valor de reserva, de modo que um cliente que prefira impor o seu sabe que está livre para isso.
  • entryShape — mapping ou sequence, deduzido do que o contêiner já contém, e unknown quando o contêiner ainda não existe ou não contém nada. unknown não é uma falha: o documento não disse que forma suas entradas assumem, então essa escolha é sua.

Como aplicá-la. Escreva uma quebra de linha onde precededByLineBreak estiver definido. Depois, uma linha para cada entrada de missingContainerKeys, da mais externa para a mais interna, cada uma sendo a chave seguida de dois-pontos — a primeira recuada em entryIndent menos indentStep vezes o número de chaves ausentes, e cada uma das seguintes indentStep mais adiante. Depois, a própria entrada, recuada em entryIndent. Quando missingContainerKeys está vazio, a entrada é a única linha que você escreve.

Leia missingContainerKeys mesmo quando você espera que o contêiner exista. Uma posição aplicada sem as chaves que precisam precedê-la produz um documento que não pode mais ser analisado, e essa é a única falha que esta resposta não pode deixar ser lida como ausente.

position conta a partir de zero, ao contrário da de um diagnóstico. Tanto line quanto character começam em 0, como os valores de posição no formato LSP que este protocolo reutiliza, enquanto line e column de uma entrada de diagnóstico começam em 1, como descrito em O que uma entrada de diagnóstico contém. Um cliente que alimenta uma superfície a partir da outra converte entre as duas.

positionEncoding nomeia as unidades em que character é medido, e é a codificação negociada no handshake. Ela é informada na resposta em vez de ficar implícita porque uma posição cujas unidades quem chama precisa adivinhar é uma posição que ele não consegue aplicar: offsets medidos de um jeito e aplicados a um buffer medido de outro corrompem o documento no primeiro caractere fora do ASCII.

Uma solicitação que não aponta para um lugar onde uma entrada pode ir é recusada em vez de respondida. Cada um destes casos é um estado da solicitação e não do workspace, então volta com o código invalid-params padrão, e uma nova tentativa não muda nada até que file ou container mude.

  • O documento não foi nomeado, não está dentro do workspace, não pôde ser lido ou não é YAML bem formado — um documento sem estrutura não tem posição a informar.
  • O caminho do contêiner não nomeia nada: não tem segmentos, ou um de 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 em vez de uma inserção.
  • O caminho chega a uma coleção que o autor escreveu em estilo flow. Acrescentar uma entrada a ela 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 em bloco com algo que não é um de seus índices. As entradas de uma sequência são endereçadas por posição, então um nome não alcança nada nela e nenhuma entrada pode ser criada para levar esse nome.

Ela lê o buffer que o editor mantém, não apenas o arquivo em disco. O cache de análise do daemon é consultado primeiro, de modo que uma posição é informada em relação ao conteúdo não salvo quando existe algum, e em relação ao próprio arquivo quando o cache não contém nada para ele.

Ela informa e nunca escreve. O método não altera nada, não resolve nada, não acessa nenhum registry nem a rede e não escreve nada em nenhum documento. Ele não compõe o texto de uma entrada nem aplica nenhuma. Compor e aplicar a edição cabe ao editor, que é onde ficam o buffer e o histórico de desfazer.

O que uma resposta de edição de documento diz a você

aggrega/editDocument é a outra metade do par acima: aquelas dizem onde uma entrada fica e deixam para você compô-la e aplicá-la; esta compõe e aplica uma, e ela escreve. Ambas continuam disponíveis, porque um cliente com um buffer não salvo e um cliente que edita o que está em disco querem metades diferentes — um editor com seu próprio histórico de desfazer posiciona o texto por conta própria, enquanto um cliente que prefere que o arquivo seja editado a ouvir onde editá-lo envia esta.

Uma chamada aplica uma edição, e o conjunto de edições é fechado. edit nomeia qual: add-component adiciona uma instância de componente sob um contêiner 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 em um nó. Não existe edição que exclua, substitua um bloco que você já escreveu, reordene algo ou escreva literalmente bytes que você fornece — então isto não é um gravador de arquivos com um nome mais restrito, e um valor fora dos quatro é recusado em vez de interpretado. A recusa lista o que você pode nomear.

Você nomeia o nó como um caminho estrutural, exatamente como as duas solicitações acima o recebem. node é o caminho a partir da raiz do documento — ["spec", "components", "web"] — e o contêiner em que a entrada vai decorre de edit. Para add-component, o caminho nomeia o próprio contêiner de componentes, porque a entrada adicionada é 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 solicita, 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 demais casos.

Um caminho em vez de um nome, pelo mesmo motivo pelo qual a solicitação de localização recebe um: um nome teria de ser procurado, e um nome que aparecesse em dois níveis deixaria o compilador decidir qual você quis dizer. Assim, um cliente que sabe qual nó está editando diz isso, e um cliente que não sabe sabe que tem uma pergunta a responder antes de editar qualquer coisa.

Todo byte que a edição não toca é preservado. O documento é analisado apenas para localizar o contêiner e a linha em que seu bloco termina; a entrada é renderizada e inserida no nível da linha. Comentários, linhas em branco, estilo de aspas, escalares folded e literal, expressões de template e o formato da quebra de linha final passam todos sem alteração, e o passo de aninhamento é medido a partir do próprio recuo do documento em vez de imposto — assim uma entrada fica no estilo em que você já está escrevendo. A mesma solicitação sobre o mesmo documento produz os mesmos bytes, de modo que um cliente pode comparar duas execuções e uma revisão lê uma edição como um único diff.

O resultado precisa ser um documento que você poderia ter digitado, e é disso que a gravação depende. O documento composto é validado contra o schema do seu próprio tipo e só chega ao disco se a validação passar. Uma solicitação que produziria algo que o schema de autoria recusa volta 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 gravado) — trazendo a propriedade que o schema não admitiria e onde ela está. O arquivo fica byte a byte como estava, de modo que uma edição recusada é indistinguível de uma nunca tentada e você pode repetir uma solicitação corrigida sobre o documento com que começou. Também é por isso que nenhuma regra é repetida aqui: pedir que um documento Release contenha um valor de desenvolvedor é recusado pelo mesmo schema que recusaria o documento digitado à mão.

O que é admissível semanticamente não é decidido aqui. Se um socket de dependência é um que o produtor declara, ou se a aplicabilidade de uma Feature é satisfeita, cabe à resolução que um build realiza, cada uma com seus próprios relatórios. Então você pode nomear uma conexão de que esta solicitação nunca ouviu falar, e um Aggregate pode definir um socket que sua entidade de catálogo não pré-declara; o que pode ser consumido por meio de um socket continua cabendo ao produtor declarar. Execute aggrega/validate nomeando uma Release, ou peça o grafo, quando essa for a pergunta.

A resposta nomeia o que foi colocado e o que chegou ao disco, e são perguntas diferentes. content contém o documento que a edição produziu nas duas modalidades de entrega. written nomeia o arquivo que chegou ao disco, e fica vazio com dryRun. container é o caminho estrutural do contêiner em que a entrada foi colocada, para que você possa localizar o que acabou de adicionar sem deduzir essa regra de novo. createdContainers nomeia os segmentos que esta edição escreveu porque o documento não os continha, do mais externo para o mais interno — vazio no caso comum em que o caminho inteiro já existia, e lê-lo é como você distingue uma entrada adicionada dentro de um bloco existente de uma que criou seu próprio bloco. file e edit repetem o que você enviou, de modo que um cliente com várias solicitações pendentes associa 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 gravação teria produzido, e o arquivo não é tocado — assim um editor pode apresentar o resultado ao autor para que ele o salve, altere ou descarte. O padrão é a gravação, porque o produto da operação é um documento editado e uma superfície que produz um deve entregá-lo: uma solicitação que não diz nada sobre a entrega edita o arquivo.

Tudo o mais que uma gravação faz, uma execução de teste também faz. O documento composto é validado contra o schema do seu próprio tipo em ambos os casos, então uma edição que uma gravação recusaria é recusada também com dryRun, nomeando a mesma propriedade — o que significa que o erro que você recebe de uma execução de teste é o erro que a gravação teria dado a você.

Uma entrada que já existe, contendo o que você pediu, é uma operação nula — o documento volta inalterado e nada é gravado. Uma entrada com esse nome contendo 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 gravação, o daemon relê o documento. O que ele mantinha para esse arquivo é descartado e sua visão no nível do workspace é redefinida, de modo que a próxima solicitação de validação, hover, autocompletar ou grafo é respondida a partir dos bytes que a edição produziu, e não da versão que ela substituiu. A própria edição lê o arquivo em disco e não o buffer que você mantém — ao contrário da solicitação de localização acima, que consulta primeiro o conteúdo não salvo. Isso é proposital: gravar a partir de um buffer não salvo colocaria na página conteúdo que o autor não havia salvado, a pretexto de aplicar uma única entrada. Salve o buffer e depois edite.

Uma solicitação que não aponta para um lugar onde uma entrada pode ir é recusada em vez de respondida, com o código invalid-params padrão, e uma nova tentativa não muda nada até que a solicitação mude. O documento não foi nomeado, não está dentro do workspace, não pôde ser lido, não é YAML bem formado ou não declara nenhum tipo contra cujo schema o resultado possa ser verificado; edit não foi nomeado ou não é um dos quatro; node não nomeia nada, ou um de seus segmentos está vazio; nenhum name foi fornecido; wire-edge não nomeou nenhum socket; set-value recebeu um mapping ou uma sequência onde cabe um escalar; o caminho do nó chega a um escalar ou a uma sequência, ou a uma coleção escrita em estilo flow, onde adicionar uma linha reescreveria bytes já presentes na página; ou o caminho do nó não alcança nada no documento.

Ela não resolve nenhuma dependência, não acessa nenhum registry e não toca a rede em nenhuma das duas modalidades de entrega.

O que a resposta de configuração efetiva abrange

aggrega/effectiveConfiguration responde a duas perguntas: qual configuração se aplica nesta sessão e qual camada decidiu cada configuração. É a mesma resposta que aggrega config show --origin imprime, calculada uma vez e informada nas duas superfícies, de modo que as duas não podem divergir sobre a origem de uma configuração.

Um source tem uma de quatro formas. O caminho absoluto de um arquivo de configuração — incluindo o arquivo global que um daemon iniciado como aggrega --config <file> serve lê, nomeado pelo caminho que lhe foi dado; uma variável de ambiente atrás de um prefixo env:, como env:AGGREGA_SIGNING_REQUIRED; uma flag global digitada na linha de comando que iniciou o daemon, nomeada como a flag, como --offline para um daemon iniciado como aggrega --offline serve; ou (built-in defaults) para uma configuração que nenhuma camada define. As três primeiras aparecem literalmente em layers. Os padrões não, porque os padrões não são uma camada que contribuiu — eles são o que se aplica onde nenhuma camada se manifestou.

Uma configuração é atribuída à camada de maior precedência que a define, qualquer que seja o valor que essa camada escreva. Um arquivo de configuração que escreve o padrão embutido, ou que repete um valor que um arquivo abaixo dele já define, é o arquivo nomeado: é ele que mantém o valor no lugar. Um arquivo define uma configuração ao conter 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 arquivo de configuração que pertence ao seu pipeline nunca é nomeado para uma chave que ele ignora. aggrega config show --origin informa segundo a mesma regra.

Toda configuração que o schema de configuração declara é contabilizada, embora nem todas com uma linha própria. O companheiro aditivo _append de uma lista é informado na linha da lista à qual ele acrescenta, de modo que uma camada que contribui apenas por meio do companheiro é nomeada na linha dessa lista e o companheiro não tem linha. Uma configuração dentro das entradas de uma lista — a política de confiança de um registry, as entradas de um anexo de plugin — é coberta pela linha dessa lista.

Mais dois limites, cada um dos quais torna uma resposta mais grosseira do que parece.

  • Uma configuraçã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 é rastreada, então uma lista montada a partir de duas camadas informa apenas a de maior precedência, e uma entrada contribuída por uma camada inferior não se distingue 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 configuração se compõe de modo que qualquer camada que a ative prevalece e nenhuma camada posterior pode desativá-la, então a primeira camada a ativá-la é a que fez do valor efetivo o que ele é. Uma camada que escreve required: false não ativa nada, então, onde toda camada que a menciona escreve false, a configuração informa (built-in defaults).

Todo valor informado é a resolução feita quando esse workspace foi nomeado pela primeira vez. Editar um arquivo de configuração não muda um valor aqui; reiniciar o daemon, sim. Isso é proposital — os valores são a configuração sob a qual toda outra solicitação sobre esse workspace é respondida, e é isso que os torna comparáveis com a raiz e a camada de configuração que o handshake informou para ele. Um cliente que mostra a configuração ao lado de um arquivo que o usuário está editando deve dizer qual dos dois está mostrando.

A atribuição às camadas é calculada quando você pergunta, com base nos arquivos como estão. Assim, um arquivo de configuração editado depois pode mover um source enquanto o valor ao lado continua como foi resolvido. As duas metades respondem a perguntas diferentes — o que está em vigor e qual camada decidiu isso — e só a primeira é fixa. Reinicie o daemon para colocá-las de novo em sintonia.

Ela informa e nunca escreve. O método não altera nenhuma configuração, não cria nenhum arquivo e não resolve nada a partir de um registry ou da rede.

O conteúdo do arquivo de uma única camada não é servido aqui. A linha de comando pode imprimir literalmente os bytes de uma camada, com comentários e formatação preservados; este método informa a resolução em vez dos bytes. Um cliente que queira o texto de uma camada tem o caminho em layers e pode abri-lo.

O que uma gravação de configuração deixa para trás

aggrega/configInit e aggrega/configCapture produzem ambos um documento de configuração, e ambos o gravam. A resposta nomeia o arquivo; abri-lo é a sua próxima ação, não um substituto para a gravação. Nenhum dos dois entrega a você conteúdo para posicionar por conta própria, a menos que você peça isso explicitamente, porque uma funcionalidade cujo produto é um documento que nunca foi gravado é uma funcionalidade diferente com o mesmo nome.

Os dois diferem no alcance, e cada resposta diz qual. Leia isso antes de mostrar o resultado.

  • A inicialização grava, por padrão, a configuração compartilhada entre todos os workspaces da máquina. Um registry e as identidades em que você confia nele costumam ser os mesmos onde quer que você trabalhe, então é para lá que a entrada vai, a menos que a solicitação envie workspace: true. scope contém o configFile que foi gravado e machineWide, que diz se ele é o compartilhado — derivado do arquivo para o qual a gravação foi resolvida, e não do que a solicitação pediu, de modo que uma resposta não pode descrever uma alteração para a máquina inteira como uma alteração local.
  • O congelamento nunca vai além do workspace. Ele não recebe destino de gravação nem substituição: todo o seu propósito é tornar um projeto autossuficiente, então ele sempre grava o .aggrega-config.yaml do próprio projeto. É por isso que sua resposta contém configFile e workspaceRoot e não declara escopo — não há alcance a informar.

A inicialização recusa em vez de sobrescrever. Um arquivo de configuração que já existe fica intocado e a recusa o nomeia, porque a inicialização é para uma configuração que ainda não existe, enquanto a gravação compartilhada à qual ela delega mescla por design. Envie force para gravar mesmo assim; a entrada do registry é mesclada ao que já existe e as demais configurações são preservadas. Uma solicitação recusada não altera absolutamente nada.

trust diz o que a política anunciada pelo registry fez, como resultados separados em vez de texto corrido. pinned significa que o registry anunciou uma política e ela foi adotada, com identities contando as identidades. notAdvertised significa que o registry foi consultado e não anunciou nenhuma, o que não é uma falha — a inicialização prossegue, e reason diz o que o endpoint fez. Um registry que não pôde ser alcançado também é informado assim, já que nenhuma política voltou e a inicialização prossegue do mesmo modo, e traz unreachable ao lado quando a própria falha mostra que o registry nunca foi alcançado: seu nome não foi resolvido, uma conexão com ele foi recusada ou não pôde ser aberta, ou uma conexão segura com ele não pôde ser estabelecida. Um registry que respondeu — com um not-found ou com um status de erro — nunca traz unreachable, então leia essa chave em vez das palavras de reason para distinguir um registry que não publica política de um que nunca foi consultado. baseline significa que a baseline embutida do hub oficial foi fixada porque nenhuma política anunciada foi adotada, com reason dizendo por quê; a entrada traz uma política, então não há nada a fixar à mão. As duas chaves respondem a perguntas diferentes, então um hub que foi consultado e não anunciou nada traz as duas, e um hub em um workspace offline — nunca consultado — traz apenas baseline, com reason dizendo que o workspace está offline. Qualquer outro registry que não anuncia nada traz apenas notAdvertised, é inicializado sem política, e o conselho que se segue é fixar as identidades à mão; offline, ele é recusado em vez de respondido. skipped significa que nenhuma busca foi tentada. Um cliente que tratasse como erro qualquer coisa diferente de pinned informaria uma configuração que funciona como quebrada.

Com dryRun, nada é criado. written é false, content contém o documento que uma gravação teria produzido, e o arquivo a que esse conteúdo se destina é scope.configFile. Nenhum diretório é criado e nenhum arquivo é tocado, de modo que um editor pode apresentar o texto ao autor e deixá-lo salvar, alterar ou descartar.

Uma execução de teste difere de uma gravação em exatamente um aspecto — ela não grava —, então realiza toda recusa que uma gravação realiza. A recusa por arquivo existente é a que importa aqui: dryRun sobre um arquivo de configuração que já existe é recusado, nomeando o arquivo, exatamente como uma gravação. É isso que torna a resposta utilizável como predicado — se a execução de teste recusa, a gravação teria recusado, pelo mesmo motivo e com a mesma mensagem. Envie force junto com dryRun para receber em vez disso a mesclagem que uma gravação com sobrescrita produziria, ainda sem gravar nada. O registry é consultado sobre sua política de confiança anunciada em qualquer das duas modalidades de entrega, porque a política nesse conteúdo é a política que uma gravação teria fixado.

O que um congelamento informa é o que ele gravou, não uma descrição disso. sockets lista cada socket de plugin que foi congelado, com os anexos congelados nele; catalogDirs contém os diretórios de catálogo. Ambos são sempre arrays, vazios em vez de ausentes.

  • socket e field não são a mesma string, e a diferença não é estética. socket nomeia o socket ao qual os anexos estão vinculados; field é a chave sob a qual eles foram escritos no arquivo. Eles diferem apenas no socket de providers, que é escrito sob uma chave no plural — então use field quando apontar para um leitor uma linha do documento e socket quando nomear o próprio socket.
  • Cada anexo traz uri, capability, function e role, presentes apenas onde o anexo tem um. Eles nomeiam o anexo em vez de reproduzi-lo por inteiro: as entradas opcionais que um anexo recebe no momento do anexo são congeladas literalmente no arquivo e não são repetidas na resposta. O arquivo é a cópia de referência.
  • captured: false é um sucesso. Um projeto cuja configuração não participa de um build não tem nada crítico para o build a congelar, então o arquivo fica como está e as duas listas voltam vazias. Tratar isso como erro informa um workspace saudável como quebrado.

Por padrão, congela-se apenas o que determina os bytes de saída — os vínculos de providers e os anexos de governança que transformam rótulos. Os controles de veredito da governança e dos linters e o socket de importação ficam de fora, porque devem variar entre ambientes e congelá-los levaria os controles de um ambiente para todo checkout. allPlugins: true amplia o conjunto para todo socket de plugin. A inclusão é por anexo, não por socket, então um socket de governança que traz um anexo de transformação de rótulos e um de veredito contribui, por padrão, apenas com o primeiro.

Todo valor é congelado em seu valor efetivo — o que resulta da configuração da máquina e da do próprio projeto mescladas —, de modo que um vínculo que hoje vem apenas da configuração da máquina é gravado no projeto e viaja com ele. As configurações de ferramentas da máquina inteira, entre elas a política de confiança de um registry, não são críticas para o build e ficam onde estão. Congelar duas vezes sobre uma configuração inalterada regrava os mesmos bytes, então um cliente pode oferecer isso livremente: uma segunda chamada deixa o documento que um leitor tem aberto exatamente como estava.

O que uma alteração de plugins diz a você

As quatro solicitações de plugins gravam todas por padrão, e se dividem pelo que gravam: duas alteram um arquivo de configuração e duas produzem documentos no workspace. Duas delas — a adição e a geração — aceitam dryRun, que faz todo o resto que a solicitação faz e não grava nada. Leia o que a própria resposta diz sobre onde a alteração foi parar em vez de deduzir isso da solicitação — para uma delas, uma solicitação que não diz nada sobre o escopo significa o alcance mais amplo.

Uma adição e uma remoção trazem ambas scope, derivado do arquivo para o qual a gravação foi resolvida. configFile é esse arquivo, machineWide diz se ele é aquele por meio do qual todo workspace desta máquina é resolvido, e workspaceRoot nomeia o workspace sobre o qual esta sessão foi aberta, de modo que uma resposta com escopo de workspace diz de qual workspace se tratava. machineWide é lido do arquivo resolvido, e não do que a solicitação pediu, e é isso que impede uma resposta de descrever uma alteração para a máquina inteira como uma alteração local.

🔴 Uma adição do tipo cli que não nomeia nem global nem workspace registra o comando para a máquina inteira. Uma extensão de comando é uma ferramenta da máquina inteira, então, sem substituição, ela é gravada no arquivo de configuração global por meio do qual todo workspace desta máquina é resolvido — e o comando que ela registra passa a ser um comando aggrega de nível superior para todo projeto dessa máquina, incluindo projetos que ninguém nesta sessão nomeou. Uma adição provider, governance, linter ou importer funciona ao contrário: elas moldam o build de um único projeto, então, sem substituição, vão para o .aggrega-config.yaml do próprio 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 levar qualquer uma das outras para o arquivo compartilhado; enviar ambos é recusado. O scope na resposta é, em qualquer caso, a declaração de referência, e um cliente deve mostrá-lo antes de agir sobre o resultado.

Uma adição nomeia o que foi colocado, e exatamente um de três campos diz que espécie de coisa era. type repete o tipo para o qual a entrada foi adicionada, e então: identity contém a identidade de entidade simples, fixada em uma versão, para um anexo governance, linter ou importer; uri contém o endereço de artefato oci:// do plugin, junto com a capability que ele agora atende, para um vínculo provider; e reference contém a referência fixada cujos comandos foram registrados, para uma instalação cli. Assim, quem chama lê na resposta que espécie de anexo foi colocado em vez de deduzi-la de novo do tipo que enviou. Uma remoção repete type e query ao lado de seu scope e nada mais — não há mais nada a informar sobre uma entrada que já não existe.

Uma adição traz também written e, com dryRun, content. written é aquilo em que um cliente se baseia para decidir o caminho: true nomeia um arquivo de configuração agora em disco que o cliente pode abrir, e com dryRun ele é false e content contém, em vez disso, o documento de configuração que a gravação teria produzido. Os dois nunca são significativos ao mesmo tempo, e o arquivo a que content se destina é scope.configFile, então nada na resposta traz uma segunda cópia desse caminho — o que importa aqui, porque o arquivo de um anexo global é aquele por meio do qual todo workspace desta máquina é resolvido.

Um plugin sem nenhuma versão publicada é recusado em vez de anexado sem versão fixada. Uma adição resolve a consulta para um único plugin e fixa sua versão publicada mais alta, de modo que a entrada que ela grava traz uma versão. Um plugin cujo repositório não publica nenhuma versão conforme é recusado com seu nome, e uma versão que uma retratação em que este workspace confia retirou é ignorada em favor da próxima abaixo.

Uma versão que a consulta nomeia é fixada mesmo quando foi retirada, e withdrawn indica isso. Uma query escrita como <name>:<version> fixa essa versão em vez da mais recente — em todos os tipos exceto provider, que é vinculado apenas pelo nome e recusa uma versão — e nomear uma versão é a substituição: onde uma retratação na qual este espaço de trabalho confia a retirou, ela é fixada mesmo assim, e a resposta traz withdrawn: true — o fato que aggrega plugin add informa como uma linha retraction: no terminal. withdrawn está ausente em todas as outras respostas, então sua presença é todo o sinal — e sua ausência não afirma que a versão não esteja retirada. Onde os marcadores de retirada de uma versão nomeada não puderam ser lidos, withdrawn está ausente e retraction traz unscreened, dizendo por quê, como acontece com uma adição que não nomeia nenhuma versão e encontra a mesma falha; uma adição que não nomeia nenhuma versão informa, em vez disso, em retraction o que a verificação de retirada concluiu sobre a versão que ela escolheu.

Um alinhamento informa se alterou algo, e esse é o campo com base no qual agir. changed separa uma gravação de um alinhamento que encontrou os registros já corretos: um arquivo inalterado fica idêntico byte a byte, então um cliente que mantém esse documento não tem nada a recarregar, e executar a solicitação duas vezes não informa nenhuma alteração na segunda vez. entity nomeia o arquivo, hostFunctions contém o conjunto derivado, e commands contém o espelho como valores em vez da linha que um terminal imprime — cada entrada com um name, uma description opcional e flags, cada flag com seu name e seus shorthand, description, type e default opcionais. A gravação é atômica, então um cliente que lê esse arquivo enquanto o alinhamento é executado nunca observa um documento parcial.

Uma geração preenche exatamente uma metade de sua resposta, e o próprio dryRun da resposta diz qual. Por padrão, as entidades são gravadas e notices contém o que a geração disse sobre as gravações que realizou. Com dryRun, nada é criado nem modificado: documents contém cada entidade gerada como o path a que se destina e seu content, de modo que um cliente pode colocá-las em seu próprio modelo de documento, onde ficam visíveis antes de serem salvas e podem ser alteradas ou descartadas. As duas metades nunca são preenchidas ao mesmo tempo, então qual modalidade de entrega foi executada se lê na resposta, e não no que foi pedido.

Onde uma solicitação de plugins GRAVA fica sempre dentro do workspace que essa solicitação nomeou; o que ela LÊ é decidido campo a campo. Um destino absoluto, um que sobe para fora da raiz e um que sai dela por meio de um link são recusados em vez de resolvidos — assim uma geração não pode criar entidades em uma árvore sobre a qual sua sessão nunca foi aberta, seja lá o que ela envie. Um caminho que uma solicitação apenas lê é uma questão separada, respondida campo a campo em vez de por uma única regra para todos: aggrega/pluginGenCatalog lê um módulo e seu overlay de onde você os selecionou, porque um módulo que você compilou fica no diretório de saída do seu toolchain e recusar-se a lê-lo ali seria recusar a operação em seu próprio propósito. aggrega/pluginSync lê seus dois caminhos dentro do workspace, porque essa solicitação trata de um arquivo que o workspace já contém. As solicitações de localização acima aceitam um caminho absoluto por ainda outro motivo — um documento que o cliente já tem aberto, nomeado pela grafia que ele mantém.

Uma solicitação à qual falta algo de que a operação precisa é recusada nomeando 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 nomeia os dois modos de seleção ou nenhum, ou à qual faltam overlay ou outputDir. Cada uma volta com o código invalid-params padrão, e uma nova tentativa não muda nada até que a solicitação mude. Uma remoção cuja consulta não corresponde a nenhuma entrada também é recusada, nomeando o tipo, a consulta e o arquivo em que procurou — esse é um estado da configuração e não da solicitação, então o que deve ser corrigido pode ser qualquer um dos dois.

Nada é perguntado de forma interativa, e a única decisão que teria sido pedida a uma pessoa chega, em vez disso, como um campo. O comando de terminal pergunta a quem estiver olhando se aceita as capacidades declaradas de um plugin de extensão de comando. Ninguém está olhando este fluxo, então cabe a quem chama obter e enviar acceptCapabilities, e uma solicitação que não o contém é recusada indicando o que enviar, em vez de instalar com base em um consentimento que ninguém deu. Um daemon iniciado sem os meios para instalar uma extensão de comando recusa de imediato uma adição cli, em vez de informar um sucesso que não instalou nada.

Quais tipos você pode oferecer a um autor

aggrega/getSchema sem kind responde quais tipos você pode nomear, e responde em duas amplitudes, porque um cliente precisa de uma diferente para cada tarefa. Leia aquela sobre a qual você está perguntando.

kinds é todo token ao qual o binário responde. entityKinds é o conjunto de tipos dos quais um autor escreve um documento. A lista ampla contém a representação intermediária, o lockfile, a configuração do workspace e os contratos dos sockets de plugins ao lado dos tipos que você escreve — schemas reais, todos eles, mas não documentos dos quais alguém escreva um arquivo. Assim, a lista ampla é a usada para ligar a associação de schemas de um editor, e a restrita é a usada para construir um seletor. Um seletor construído a partir da lista ampla oferece valores que nenhum schema de autoria aceita, e o autor só encontra a recusa depois de escolher um.

O conjunto restrito é mais restrito também que os tipos de entidade, e nenhum schema diz a você quais. Um tipo pertencente à 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, inline ou a partir de um arquivo que esse campo importa, então não há documento de workload a endereçar por si só — consulte a superfície de autoria do Workload para saber onde esse conteúdo fica. Seu schema fixa apiVersion e kind exatamente como o schema de um tipo de autoria faz, porque é isso que permite validar o conteúdo onde ele está; os valores fixos identificam o conteúdo e não o tornam endereçável. Então não são um sinal de que um tipo seja um a esboçar. entityKinds traz a resposta, e nada nos bytes do schema a traz.

Cada entrada de entityKinds traz as duas grafias de que um cliente precisa, e nenhuma é derivável da outra. kind é o token em minúsculas com hifens — envie-o de volta como kind a este método ou a aggrega/scaffoldEntity. documentKind é o valor que o próprio documento traz em seu campo kind: de nível superior. Os dois diferem em mais do que maiúsculas e minúsculas para um tipo cujo nome tem mais de uma palavra: nada que você possa fazer com featurerecipe chega a FeatureRecipe. Pegue cada um da entrada em vez de derivar um do outro, e não sobra nenhum mapeamento para o cliente manter.

Cada entrada diz também quais operações aceitam um documento do seu tipo, de modo que um controle que oferece essas operações sobre um documento oferece apenas as que não o recusam por causa do seu tipo. acceptedBy traz três booleanos, cada um presente em toda entrada, e cada um diz respeito a um documento do tipo nomeado por si só — pelo seu caminho, ou pelo seu nome para inspeção — sem nada mais enviado ao lado. singleEntityValidation indica se aggrega validate <path> verifica um documento do tipo, em vez de recusá-lo e nomear o escopo do catálogo inteiro ou da Release que o verifica em seu lugar. publication indica se aggrega/publishEntity nomeando apenas o documento o publica: um Plugin é false, porque sua publicação vincula também o executável que uma solicitação nomeia em plugin, então uma solicitação que nomeia apenas o documento é recusada; um Manifest e uma Release são false porque nenhum dos dois tipos é publicado. inspectionByName indica se aggrega/entityDefinition resolve um nome para uma entidade do tipo, com o nome enviado 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 onde só uma capacidade declara esse nome. Um true diz que a operação não recusa o documento por ser desse tipo; ela ainda pode recusar um documento específico pelo que o documento diz.

Não mantenha uma lista própria. Quais tipos existem é uma propriedade do binário com que você está falando, então uma lista escrita em um cliente está correta no dia em que é escrita e deixa de estar no dia em que um tipo é adicionado — e o que o autor vê então é o seu tipo ausente do único controle que deveria oferecê-lo. Pergunte, e a resposta acompanha o binário.

As duas metades chegam juntas, e só quando você não nomeia nenhum tipo. Uma solicitação que nomeia um tipo é respondida com o schema desse tipo e não traz nenhuma das duas listas, de modo que a pergunta que você fez pode ser lida na resposta. Um token ao qual nenhum schema responde é recusado com o conjunto válido completo na mensagem, com o código invalid-params padrão, então um erro de digitação é uma solicitação a corrigir, e não algo a perguntar a uma pessoa.

Ela responde em um workspace que não contém nada. O vocabulário é compilado no binário, então isso não precisa de documento, lockfile nem catálogo — que é justamente o workspace em que está um autor que começa seu primeiro documento.

O que uma resposta de scaffold oferece a você

Esta seção trata da criação de rascunhos. A outra forma do método escreve um exemplo executável, e sua resposta é descrita junto com o método acima.

aggrega/scaffoldEntity devolve texto. skeleton é YAML para o tipo que você nomeou: todo campo que o schema desse tipo exige, na ordem em que o schema os declara. Um campo que o schema fixa em um único valor chega preenchido — apiVersion e kind são os que você vai notar —, metadata.name traz o name que você enviou, e todo outro valor obrigatório chega como um placeholder do tipo que o schema declara ali: uma string vazia, um zero, um false, uma lista vazia, um mapeamento vazio. kind repete o token para o qual o documento foi derivado, de modo que um cliente com várias solicitações pendentes atribui uma resposta a partir da própria resposta em vez de manter uma correlação própria.

Ele não escreve nada, e é em torno disso que se deve projetar. O método não cria nenhum arquivo, não escolhe nenhum caminho e não toca em nenhum diretório. O que você recebe é um documento a escrever, não um documento que foi escrito — então um editor coloca o texto em um novo buffer não salvo que o autor pode ler, editar ou descartar, e o momento em que um novo arquivo chega ao disco permanece onde estão o buffer e o histórico de desfazer. Nenhuma outra solicitação pega esse documento e o coloca em algum lugar em seu nome; decidir onde um novo documento fica cabe ao editor.

Ele não resolve nada e não precisa de nada do workspace. O documento é derivado dos schemas que o binário traz, então o método não alcança nenhum registry nem nenhuma rede, não consulta nenhum catálogo e não lê nenhum arquivo. Ele responde da mesma forma em todo workspace, inclusive em um diretório vazio sem nenhum documento Aggrega ainda — que é exatamente o workspace em que está um autor que começa seu primeiro documento, e onde a maioria dos outros métodos daqui iria querer primeiro um documento ou um lockfile.

A mesma solicitação dá os mesmos bytes onde quer que seja feita. O documento é produzido por um único cálculo compartilhado com as outras superfícies que oferecem essa capacidade, de modo que um editor e um assistente aos quais se pedem o mesmo tipo e o mesmo nome mostram ao autor o mesmo texto inicial.

O esqueleto traz os campos que seu tipo exige, e não é um documento pronto. Ele traz os campos obrigatórios e nada mais: um campo opcional que você queira é um que você adiciona, e todo placeholder é um valor ainda pendente. Preencha os placeholders e então execute aggrega/validate no buffer. Para uma entidade de catálogo de um tipo que aggrega validate verifica como entidade única, esse método nomeia todo placeholder ainda pendente, cada um em sua chave com o que ele aceita, pela mesma leitura que o comando aplica ao arquivo salvo — incluindo um placeholder que o schema admite vazio; capability e implements de uma Recipe ou FeatureRecipe gerada são os que você vai encontrar. Para qualquer outro tipo, ele submete o buffer ao schema do seu tipo, de modo que um placeholder que o schema recusa vazio — uma versão, por exemplo — volta como constatação desse schema, e um que o schema admite vazio não gera nenhuma. Validação ao vivo descreve a entrada com que cada placeholder chega.

O que uma resposta de importação informa

aggrega/import converte uma fonte escrita para outra ferramenta em rascunhos de documentos Aggrega, e os grava — ao contrário do scaffold acima, que devolve texto para você. written nomeia cada arquivo que chegou ao disco, relativo a outputDir; files traz cada arquivo que a requisição grava com o seu content, tenha sido gravado ou não — cada rascunho que o importador produziu, depois o registro do que a importação gravou, ou, sob sync, o que a sincronização altera. Os dois respondem a perguntas diferentes, então leia aquele que corresponde à sua pergunta: o que está agora no disco, ou o que foi produzido.

Você escolhe para onde vão os rascunhos, ou deixa isso para a raiz do espaço de trabalho. outputDir é opcional, assim como aggrega import --output-dir e o output_dir da ferramenta import do assistente: uma requisição que não nomeia nenhum cria os rascunhos sob a raiz do espaço de trabalho — onde aggrega import grava quando não recebe nenhum destino, onde quer que seja executado — e uma requisição que nomeia um cria os rascunhos ali. Um diretório nomeado é um caminho dentro do espaço de trabalho, e um valor relativo é resolvido em relação à raiz do espaço de trabalho, e não em relação a um diretório em que o daemon esteja por acaso. A source que você converte é o outro caso e não fica confinada dessa forma: foi você quem selecionou esse arquivo ou diretório, então ele é lido onde quer que esteja, e lê-lo ali não muda onde os rascunhos vão parar. O diretório é criado se não existir. Sob dryRun nada é gravado, e cada rascunho ainda nomeia o caminho a que se destina, relativo ao outputDir que a resposta nomeia — o diretório que você enviou, ou a raiz do espaço de trabalho.

Uma requisição nunca sobrescreve um Aggregate que já está em outputDir. Um Aggregate é o documento que um autor continua editando depois de criado o rascunho, então uma requisição em que um dos rascunhos cairia sobre um arquivo que se lê como um Aggregate é recusada, nomeando o rascunho e onde o Aggregate está, e absolutamente nada é gravado — também sob dryRun, já que uma execução de teste recusa o que a gravação recusa. Em vez disso, envie sync para atualizá-lo em relação à fonte, ou nomeie outro outputDir para criar o rascunho ao lado dele. Qualquer outro arquivo que já esteja em um caminho de rascunho é sobrescrito, e um arquivo que uma importação anterior criou como rascunho e que esta não cria é deixado onde está. Toda requisição que cria algum rascunho também grava .aggrega-import.json em outputDir, o registro do que a importação gravou — o target que lhe foi enviado, quando lhe foi enviado um, o snapshot do catálogo que ela leu, quando leu um, e cada arquivo de rascunho e, em um Aggregate ou uma Release de rascunho, cada chave em qualquer profundidade, com um digest do texto gravado ali, sendo qualquer outro arquivo de rascunho registrado por inteiro — e files e written o trazem depois dos rascunhos. É JSON, então nada que leia os documentos YAML do espaço de trabalho o lê; sync, assim como aggrega import --sync, o lê para atualizar os rascunhos em relação à sua fonte. Um sync enviado sem target cria rascunhos para o destino que o registro nomeia, então cria o Manifest que a importação anterior criou; um enviado com um target cria rascunhos para ele, e o registro passa então a nomeá-lo. Um destino registrado ao qual nenhuma Recipe do catálogo se vincula é recusado como um enviado é, e a recusa diz que o destino é o registrado. Como uma Release de rascunho é registrada chave por 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 a deixa intacta byte a byte.

Envie sync para atualizar em relação à fonte o que uma importação anterior criou como rascunho em outputDir, alterando apenas o que a importação gravou. Cada parte é avaliada de três formas — o que o registro diz que a importação gravou ali por último, o que está no disco e o que a fonte produz agora. Uma parte que a fonte deixou como a importação a gravou por último permanece exatamente como está no disco, tenha um autor a editado ou não. Uma parte que a fonte alterou é gravada de novo, uma parte que ela descartou é removida — um arquivo de rascunho é excluído por inteiro — e uma parte que ela ganhou é adicionada ao lado das partes que o rascunho nomeia ao seu redor, cada uma apenas onde o que está no disco é o que a importação gravou por último e não contém nada que um autor tenha adicionado. Todo o resto permanece intacto byte a byte: uma chave que um autor adicionou em qualquer lugar — um parâmetro, uma Feature, também sob uma instância de Component de rascunho, outro Component — um comentário não escrito diretamente acima de uma chave de rascunho, e cada arquivo que o registro não lista. Uma sincronização em um diretório que não contém nenhum registro e nada em seus caminhos de rascunho grava o rascunho inteiro, como faz uma requisição sem sync.

drift é o que uma sincronização atualizou, e é a resposta a “a fonte mudou?”. Lista cada parte que a sincronização alterou — ou, sob dryRun, cada parte que ela alteraria — na ordem em que o rascunho as nomeia, cada uma como change (added, removed ou changed), file, o arquivo de rascunho em que ela está, relativo a outputDir, e key, as chaves que levam até ela em um Aggregate ou uma Release de rascunho, como uma lista, de modo que uma chave que contém um ponto continua sendo uma única entrada; key fica vazio onde a parte é o arquivo inteiro, que é como é nomeado um arquivo de rascunho que a sincronização exclui. aggrega import imprime as mesmas entradas na saída de erro padrão como <change> <key> in <file> ou <change> <file>, e seu código de saída sob --sync --dry-run diz se a fonte se desviou; esta interface não tem código de saída, então envie sync com dryRun e verifique se drift está vazio. drift é uma lista vazia para uma requisição que não é uma sincronização, para uma sincronização em dia com sua fonte e para uma sincronização cujo importador não conseguiu terminar. Sob sync, files traz cada arquivo de rascunho que a sincronização altera, com o conteúdo que ela lhe dá, depois o registro, quando ele também muda, e written nomeia aqueles que chegaram ao disco — então uma sincronização em dia responde a ambos com listas vazias. Um arquivo de rascunho que a sincronização exclui é nomeado em drift e em nenhuma das duas listas: sua entrada removed, com uma key vazia, é o único registro que a resposta faz dele, e sob dryRun nomeia o arquivo que uma gravação excluiria.

Uma sincronização nunca reescreve o que um autor escreveu e, em vez disso, recusa. Uma sincronização que alteraria ou removeria uma parte que um autor editou, adicionaria uma parte onde um autor já escreveu uma, ou removeria uma parte que contém algo que um autor adicionou é recusada, nomeando cada uma dessas partes e o motivo em uma linha própria, nas palavras que aggrega import --sync usa — <file> <key>: <why>, ou <file>: <why> para um arquivo inteiro — e nada é gravado; um comentário escrito diretamente acima de uma chave de rascunho edita essa chave. Uma sincronização sobre um Aggregate que nenhum registro lista é recusada nomeando o Aggregate e o registro, assim como uma cujo registro não pode ser lido, já que sem o registro suas partes não podem ser distinguidas das de um autor. Ambas as recusas voltam como o erro invalid-params, também sob dryRun, e nomeiam sync. Reconcilie à mão cada parte nomeada, ou restaure o que a importação gravou ali, e envie a requisição novamente.

🔴 halted: true não é um erro, e tratá-lo como tal é o engano a evitar no design. Um importador que não conseguiu converter tudo ainda cria rascunhos do que conseguiu: a resposta traz esses rascunhos, written os nomeia e diagnostics diz o que ficou de fora. Essa é a resposta mais útil que a operação dá, e ela chega como resultado e não como falha justamente para que você possa mostrar ao autor as duas metades. Sob sync a mesma resposta não grava nada — files, written e drift ficam vazios — porque um rascunho parcial se leria como uma fonte que descartou cada parte que o importador não alcançou. Uma fonte que o importador não conseguiu ler de forma alguma é um caso diferente e volta, sim, como erro.

Cada diagnóstico traz severity e message, mais code onde o importador atribuiu um. Ramifique por code quando quiser reagir a uma condição específica e mostre message ao leitor; severity vem do mesmo conjunto em que todo socket de plugin reporta — halt, warn, info — então halted é um resumo das entradas, e não um julgamento à parte. files, written, drift, diagnostics e decisions são sempre arrays, vazios em vez de ausentes.

decisions diz onde a importação adivinhou. Traz uma entrada por nó de origem que o importador mapeou, na ordem do importador e exatamente como o importador a reportou: sourceNode, o id, o type e o 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 de seus sinais contribuiu, sob table, category, domainLabels, shape e name; chosen, o target que ele escolheu, o mode em que o gravou — 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 onde o importador não ponderou nenhum, chosen onde ele não fez nenhuma escolha, e rationale e swapHint onde ele não escreveu nenhum. Cada valor é do próprio importador — como ele pontua um candidato e onde caem seus níveis são escolhas dele — então mostre uma entrada como o relato dele sobre o mapeamento, e não como um veredito. As decisões chegam tanto sob dryRun quanto com halted verdadeiro: os palpites de uma importação parcial são exatamente o que um autor que a revisa precisa, e um importador que não reporta nenhuma responde com uma lista vazia. Onde você 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 fonte, a menos que você o nomeie. O reconhecimento usa as assinaturas que os importadores declaram — tanto os do catálogo do espaço de trabalho quanto os importadores básicos do compilador — e que a entidade Plugin de cada importador registra — a sintaxe em que uma fonte é lida, os nomes de arquivo a que uma assinatura se aplica e os caminhos que a árvore analisada deve ou não deve conter — de modo que o próprio daemon não conhece nenhum formato e o formato de um novo importador é reconhecido sem que nada mais mude. A detecção lê apenas a fonte que você enviou — de um diretório, apenas os arquivos que os padrões de arquivo de uma assinatura selecionam — e nenhuma rede, analisando cada arquivo que lê com o parser que o catálogo do espaço de trabalho fornece para uma sintaxe — ou, para uma sintaxe para a qual o catálogo não fornece nenhum parser, o que o próprio compilador traz — uma vez para cada sintaxe em que uma assinatura aplicável ao seu nome o lê; o importador então lê a fonte com o mesmo parser. Uma assinatura que não declara nenhum padrão de arquivo se aplica ao arquivo que você enviou, seja qual for seu nome, e a nenhum arquivo de um diretório; as assinaturas dos importadores de Langflow, Flowise e n8n são desse tipo e leem JSON, e a do importador de Dify lê YAML, então reconhecer um arquivo enviado sozinho o lê como JSON e como YAML, o que não exige nenhum parser no catálogo do espaço de trabalho: o compilador traz um parser de JSON e um de YAML, e um que o catálogo forneça é usado no lugar dele. Uma fonte que nenhuma assinatura reconhece é recusada pedindo format e nomeando os formatos que os importadores anunciam — ou, para um diretório, pedindo um de seus arquivos enviado sozinho ou um format cujo importador declare padrões de arquivo, nomeando apenas esses — sob a condição No importer recognises the source (Nenhum importador reconhece a fonte); uma fonte reconhecida por assinaturas de mais de um formato é recusada nomeando-os, sob a condição More than one importer recognises the source (Mais de um importador reconhece a fonte). O data de cada recusa traz o code e o shortCode de sua condição, de modo 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 absurdos com toda a confiança. format na resposta é o que foi usado, detectado ou nomeado, de modo que um cliente que o omitiu fica sabendo o que obteve.

Um diretório que você envia é lido nos arquivos que seu importador nomeia, e um que não pode ser lido é um erro. Onde source nomeia um diretório, o importador recebe os arquivos dele que os padrões de arquivo declarados por suas assinaturas selecionam, excluída a pasta de saída de build do workspace dist/, cada um nomeado pelo seu caminho dentro do diretório, em ordem, ao lado dos arquivos que sua entrada plugins.importer nomeia sob with.sources. Um importador que não declara padrões de arquivo, um diretório que não contém nenhum arquivo que eles selecionem, um arquivo do diretório e um arquivo de with.sources com o mesmo nome, e um link entre os arquivos que a importação leria, ou para um diretório, que leva para fora do diretório voltam, cada um, como um erro com o código da condição, sem que nada seja gravado.

Qual importador é executado é uma decisão do espaço de trabalho, não da requisição. O formato é resolvido para o importador que o anuncia entre os plugins do catálogo do espaço de trabalho e os importadores básicos do compilador — aquele que uma entrada plugins.importer na configuração do espaço de trabalho anexa, onde anexa um deles — de modo que uma requisição não pode selecionar um módulo nem apontar para um no disco. Um formato que nenhum importador anuncia é recusado nomeando o formato, e um formato que dois importadores anunciam sem que nenhum esteja anexado — entre eles um importador básico 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 básico que a máquina ainda não tem é obtido uma vez, pela primeira importação que precisa dele. Ele vem do registry padrão do espaço de trabalho, restrito ao módulo que a versão do compilador publica e verificado como um pull verifica um plugin que obtém — sua assinatura sob a política de confiança desse registry e as funções de host que ele usa — e é mantido no cache de conteúdo do espaço de trabalho, que é a única coisa gravada para ele: nenhum lockfile e nenhum registro de plugins confiáveis. Toda importação posterior o lê dali e não acessa nenhum registry. Um módulo que não passa na verificação é um erro com o código de sua condição, e nada é mantido; um que não pode ser obtido — o espaço de trabalho está offline, seu registry não pode ser alcançado ou o registry não o contém — é um erro sob A plugin’s .wasm is not on this machine (O módulo de um plugin não está nesta máquina), que nomeia o importador, sua versão e o que coloca seu módulo na máquina. A própria requisição não nomeia nenhum registry, e uma importação que já tem na máquina todos os importadores e o catálogo que lê não acessa nenhuma rede.

Quando o espaço de trabalho não nomeia nenhuma pasta de catálogo, a importação lê o catálogo que o seu registry padrão publica. Um espaço de trabalho em que nem workspace.catalog_dirs, nem AGGREGA_CATALOG_DIRS, nem a raiz nomeiam uma pasta de catálogo lê o catálogo da biblioteca padrão como um único snapshot assinado, em catalog/snapshot no seu registry padrão. Um snapshot é obtido uma única vez: sua assinatura é verificada sob a política de confiança desse registry, e ele é mantido no cache de conteúdo do espaço de trabalho e lido ali como uma pasta de catálogo, vinculado ao seu digest, sem que nenhum registry seja consultado de novo por ele. Qual snapshot uma requisição lê: com upgrade, o mais recente; caso contrário, aquele que o registro em outputDir nomeia, obtido pelo seu digest onde a máquina não o tem; caso contrário, aquele que o espaço de trabalho obteve por último como o mais recente; caso contrário, o mais recente. O registro que a importação grava nomeia o snapshot que ela leu, pelo seu digest, de modo que uma requisição posterior no mesmo outputDir lê o mesmo catálogo. Na postura offline, uma requisição que precisaria obter um snapshot é um erro sob The workspace is offline and the step needs the network (O espaço de trabalho está offline e a etapa precisa da rede), que nomeia o que executar, e upgrade é recusado independentemente do que a máquina tenha, já que só o registry pode dizer qual snapshot é o mais recente. Um registry que não publica nenhum snapshot deixa a importação sem catálogo, e uma entrada warn em diagnostics informa isso. Um espaço de trabalho que nomeia uma pasta de catálogo importa com base nela e não obtém nenhum snapshot, e upgrade não muda nada ali.

Sob dryRun nada é criado. written fica vazio, files traz os mesmos arquivos que uma gravação teria produzido — com sync, os arquivos que a sincronização gravaria, ao lado do drift que ela atualizaria — e nenhum diretório é criado — de modo que um editor pode colocá-los diante do autor para salvar, alterar ou descartar. Todo o resto que uma gravação faz é feito: o mesmo importador é executado sobre a mesma fonte e reporta os mesmos diagnósticos, então uma fonte que uma gravação recusaria também é recusada aqui. Um importador básico ou um snapshot do catálogo obtido sob dryRun é mantido no cache de conteúdo como em uma gravação, porque adquirir aquilo sobre o que a importação é executada faz parte de executá-la, e não de posicionar os rascunhos.

Um caminho que o importador retorna é mantido dentro de outputDir. Os caminhos dos rascunhos vêm do importador, e não de você, então um caminho que sobe para fora do diretório de saída é recusado e absolutamente nada é gravado — nem mesmo os rascunhos cujos caminhos estavam corretos. A recusa nomeia o caminho problemático, e é isso que indica que é o importador que deve ser corrigido, e não a sua requisição.

Qual pergunta cada requisição de entidade responde

Quatro requisições aqui informam sobre uma entidade, e elas não são intercambiáveis. Escolher entre elas é uma questão do que você tem em mãos quando pergunta.

Você tem em mãos um cursor. aggrega/hover e aggrega/resolve recebem um arquivo e uma posição e deduzem qual entidade se pretende a partir do que está escrito ali. Elas cobrem as formas de referência que um documento realmente contém — um valor extends, um tipo de componente ou de feature, o implements de uma Recipe, as referências a recipes de um Manifest, os dois ponteiros de caminho de uma Release, um destino de uses e o próprio metadata.name de uma entidade. Recorra a elas quando o cursor do usuário for a coordenada: o usuário está lendo um documento e quer saber para onde aponta uma referência.

Você tem em mãos um nome. aggrega/entityDefinition recebe a identidade diretamente. Nada precisa estar aberto, nenhuma posição está envolvida, e a entidade não precisa estar mencionada em nenhum lugar que o cliente possa encontrar. Recorra a ela quando o usuário digitou um nome, escolheu um em uma lista ou seguiu algo cuja identidade seu próprio cliente já conhece — um hover exige que você primeiro encontre algum lugar onde o nome esteja escrito, um trabalho que você não precisa fazer.

Você 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 ela para preencher um seletor e depois passe um nome escolhido para aggrega/entityDefinition.

Você tem em mãos uma Release. aggrega/releaseClosure responde sobre uma Release, e não sobre uma entidade, e é a seção abaixo.

A definição que uma requisição por nome retorna é a entidade como resolvida, e não como algum arquivo a declara. Um Component ou uma Feature que estende uma base volta trazendo o contrato dessa base, que não aparece em nenhum lugar do documento que declara seu nome — então a resposta é sobre o que a entidade é, e ler o arquivo você mesmo não daria a mesma coisa.

Ela chega como um documento YAML, e não como estrutura dentro da resposta, e isso é proposital: um pilar de esquema tem várias formas de autoria — conteúdo escrito por extenso, uma referência a um documento compartilhado, ou o marcador que diz que o conteúdo vem de uma base — e o documento reproduz aquela a que a resolução chegou, na própria ordem de chaves do autor. Analise-o como documento se precisar dos campos dele; mostre-o como está se for colocá-lo em um painel.

Distinguindo as duas recusas por nome

Um nome que não se resolve em nada é recusado em vez de respondido com um documento vazio, porque uma resposta vazia apresentaria um erro de digitação como uma entidade sem nada a dizer sobre si mesma. Há duas formas de um nome não se resolver em nada, elas pedem coisas diferentes do leitor, e você as distingue pelo que o data do erro traz, e não lendo a mensagem:

  • Nenhum file em data. Nada no espaço de trabalho declara esse nome e nenhum nível do catálogo o resolve. Quase sempre é a requisição que deve ser corrigida — um erro de digitação, ou um nome de um catálogo que este espaço de trabalho não tem em seu caminho de busca.
  • Um file em data. Um documento do espaço de trabalho de fato declara esse nome, e ainda 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 corrige. Onde exatamente um documento que o catálogo leu e recusou declara esse nome — a causa habitual — a mensagem começa por essa recusa, declarada uma única vez: sua categoria e seu código curto, o documento pelo caminho com que é reportado, e o que há de errado com ele, como a linha e a restrição que ele viola; depois, observa que o arquivo foi ignorado no carregamento e lista qualquer outro arquivo que o carregamento recusou. Caso contrário, a mensagem nomeia o documento que o declara, lista os arquivos que o carregamento recusou e diz de onde este espaço de trabalho lê entidades locais e o que mudar para que o documento seja lido — a explicação que ela omite onde um documento recusado declara o nome, porque esse documento já está onde o catálogo lê.

Ambas trazem o código entity-not-resolvable, então ramifique pela presença de file, e não pelo código.

Perguntando sobre uma coordenada

Você tem em mãos uma referência de registry. Envie-a como name de aggrega/entityDefinition, e a resposta é a entidade publicada nessa coordenada, na mesma forma de resultado que um nome recebe, mais published, preenchida a partir do que foi publicado, e não do que um catálogo resolveu:

  • definition é o documento da entidade exatamente como foi publicado. Uma coordenada cuja entidade foi publicada com os arquivos que declara traz um arquivo compactado, e o documento é extraído dele; uma cuja entidade não declara nenhum arquivo traz seu documento inalterado, e a entidade de um Plugin é lida de seu manifesto, e não do executável publicado com ele. Nenhuma herança é aplicada.
  • authoredLength é o comprimento desse documento, porque aqui a definição é um documento de autoria, e não a renderização de um resolvido.
  • file fica vazio, porque uma entidade lida de um registry não tem nesta máquina nenhum documento a nomear.
  • publishScope é omitido: você já tem em mãos a coordenada, que é onde a entidade está publicada.
  • published é o que foi lido, e está presente nesta resposta e em nenhuma por nome: a reference; archive, se seus bytes eram um arquivo compactado do qual o documento foi extraído — false onde a coordenada continha o próprio documento; o mediaType que o manifesto declara; e o manifestDigest desse manifesto, que você pode enviar depois de @ no lugar da tag para ler exatamente os mesmos bytes de novo.

A requisição chega ao registry que a referência nomeia, com as credenciais do usuário com que este daemon é executado e a postura de rede deste espaço de trabalho, então um espaço de trabalho offline a recusa. Os bytes obtidos são verificados contra o digest que o próprio manifesto do artefato registra para eles e contra nada mais — nenhuma assinatura é verificada e nenhuma retirada é reportada — e nada é gravado. Uma referência que não pode ser lida é recusada com entity-not-resolvable, e a mensagem começa com o código curto da condição que diz o porquê — as mesmas condições que aggrega inspect reporta — e termina com o que fazer a respeito. Uma referência que não nomeia nenhum repositório, ou nem uma tag nem um digest, é uma requisição malformada e é recusada como parâmetros inválidos.

Um fechamento 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 — seus nós, as fronteiras em que estão, o que está ligado a quê, e os valores e anexos que cada nó traz. É a imagem.

O fechamento diz o que foi incluído para construí-la, e em quais versões. Cada entidade que a Release alcança, tenha ela se tornado um nó ou não; os documentos compartilhados em que essas entidades se apoiam; e os plugins que dão forma à saída. É a lista de materiais.

Nenhum pode ser recuperado 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 todo build e não é nó em nenhum deles — e um nó não traz a versão para a qual seu tipo foi resolvido. Assim, um leitor que pergunta “por que esta versão mudou?”, “o que alterar este documento compartilhado afetaria?” ou “do que esta Release realmente depende?” está pedindo o fechamento, e um leitor que pergunta “o que esta Release implanta?” está pedindo o grafo.

O que a requisição de fechamento não faz. Ela não renderiza nada e não publica nada do que encontra. Em particular, não emite nenhum aviso de drift nem nenhum aviso de renderização: esses pertencem à requisição que os pediu, e publicar substitui uma camada inteira de diagnósticos, então uma listagem que publicasse apagaria o que a requisição do grafo já havia colocado diante do usuário. Peça o grafo quando quiser o veredito de drift. A única coisa que ela de fato publica não é uma constatação própria: uma requisição que encontra o lockfile ausente retira o aviso de drift que se apoiava nele, seja qual for a requisição — veja Ciência do lockfile.

Ela exige um lockfile, assim como o grafo. As versões que a listagem reporta são aquelas para as quais esta Release foi resolvida, e um espaço de trabalho que ninguém preparou ainda não as resolveu. Uma listagem produzida sem lockfile reportaria o que o catálogo por acaso contém hoje, o que é uma pergunta diferente de saber do que esta Release depende. A recusa nomeia o lockfile e a Release, de modo que um cliente pode oferecer aggrega pull --release <release> diretamente.

kind em uma entrada de fechamento está presente apenas onde é conhecido. Uma referência é coletada a partir de uma posição em um documento, e algumas posições dizem para que tipo de entidade apontam, enquanto outras não. O campo é reportado onde o local da referência registrou um e omitido onde não registrou, em vez de adivinhado a partir da forma do nome. Ele é reportado como a palavra que um autor escreve no início de um documento, que é a mesma palavra que toda interface que reporta um fechamento usa para a mesma entrada.

A mesma palavra pede o mesmo documento em outros lugares. aggrega inspect <release> --closure responde a essa pergunta na linha de comando, e o modo release da ferramenta describe a responde pelo protocolo de ferramentas do assistente. Os três executam uma única resolução sobre a Release, então não podem chegar a discordar sobre do que uma Release depende. Veja aggrega inspect, “O fechamento de dependências”.

Modelo de cache

As operações são orientadas pelo cache: chame aggrega/validate para um arquivo antes de hover / completion / resolve / diagnostics sobre ele. Essa chamada de inicialização não precisa de uma Release — uma validação que não nomeia nenhuma ainda analisa o buffer e preenche o cache — então essas operações funcionam em um espaço de trabalho que não tem nenhuma Release a nomear. O cache de análise é conferido com a data de modificação em disco de cada arquivo a cada leitura, de modo que edições externas (um salvamento no editor, um git checkout) são detectadas automaticamente — o aggrega/invalidate do editor é uma otimização, não um requisito de correção.

O cache pertence ao espaço de trabalho que o inicializou. Um arquivo validado em um espaço de trabalho fica em cache para esse espaço de trabalho, então o mesmo caminho consultado em outro é reportado como ainda não validado, em vez de respondido a partir da entrada do primeiro. É isso que impede que uma pergunta sobre um segundo espaço de trabalho seja respondida de forma errada ou custe ao primeiro seu estado já aquecido — e aggrega/invalidate também limpa apenas o espaço de trabalho que nomeia.

Pedindo diagnósticos enquanto uma validação está em execução

Uma validação inicializa duas coisas sobre um arquivo — a análise que ela entrega às outras operações e as constatações que reporta — e as inicializa com um instante de diferença. aggrega/diagnostics é a única requisição que lê ambas: ela precisa da análise para saber que o arquivo é um sobre o qual pode responder, e responde a partir das constatações. Então uma requisição que chegasse entre esses dois instantes estaria decidindo que pode responder quando ainda não há nada com que responder.

Em vez disso, ela espera. Envie aggrega/diagnostics para um arquivo que está sendo validado agora e a resposta chega quando essa validação termina, trazendo o que ela encontrou. Há uma única resposta correta para o arquivo, seja qual for o momento, e é essa a resposta que você recebe — nunca é uma lista vazia para um arquivo cuja validação está prestes a reportar erros, que é a única resposta errada da qual um cliente não consegue se recuperar, porque nada leva você a perguntar de novo sobre um arquivo 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 da análise, então não têm nada a esperar e nunca esperam.

Duas coisas encerram a espera antes do tempo, e você já tem ambas. $/cancelRequest para o id dessa requisição a interrompe, e um aggrega/shutdown cooperativo a interrompe. Nenhuma das duas precisa de nada a mais na requisição.

E a espera é limitada. Se a validação não tiver terminado dentro do prazo que o daemon lhe concede, a requisição é recusada com o código validation-in-flight em vez de respondida vazia — veja Códigos de erro. Essa recusa significa que o trabalho que você está esperando está de fato em andamento, então o que fazer é perguntar de novo em breve; não é um sinal para enviar outra validação, o que acrescentaria trabalho e não responderia nada.

Um daemon que executa requisições uma de cada vez as responde na ordem de chegada, então nada se sobrepõe e nenhuma espera jamais acontece. Um daemon que as executa de forma concorrente responde às mesmas perguntas da mesma forma, e é a espera que garante isso: a resposta que você recebe é a resposta que uma ordenação serial teria dado.

Tamanhos em uma resposta

Uma resposta que reporta uma quantidade de bytes a reporta duas vezes: como o 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 toda resposta que traz um tamanho.

Exiba a forma escrita e calcule com o número. O objetivo de enviar ambos é que um cliente nunca precise formular um tamanho por conta própria: o daemon o escreve com o mesmo formatador que a linha de comando usa, de modo que aggrega cache status e aggrega/cacheStatus mostram um dado cache de forma idêntica, até o arredondamento. Um cliente que compusesse seu próprio texto se afastaria 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, de modo que um tamanho lido de uma resposta pode ser enviado de volta na próxima requisição sem ser reescrito. Acima de bytes, o texto traz uma casa decimal, de modo que expressa a quantidade como um leitor quer vê-la, e não até o byte; quando você precisar da contagem exata, é para isso que serve o campo numérico.

Onde o número é opcional, o texto é opcional junto com ele, e os dois nunca estão presentes pela metade: o tamanho do plugin em uma resposta de publicação traz pluginSize e pluginSizeText juntos ou nenhum dos dois.

Toda requisição nomeia o espaço de trabalho de que trata

Envie workspaceRoot em toda requisição: o caminho absoluto da raiz do espaço de trabalho sobre o qual essa requisição atua. O daemon não tem nenhum espaço de trabalho próprio e não se lembra de nenhum entre requisições, então aquilo sobre o que uma requisição é respondida é o espaço de trabalho que ela nomeou e nada mais. Duas requisições que nomeiam dois espaços de trabalho recebem duas respostas, e nenhuma pode ver as entidades, Releases, análises em cache ou diagnósticos da outra.

Uma requisição que não nomeia nenhum é recusada com o erro invalid-params padrão que nomeia o parâmetro, e o mesmo acontece com um valor vazio, que não declara nenhum espaço de trabalho e é respondido como um ausente. Outras duas formas são recusadas pelo mesmo motivo, cada uma nomeada 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 requisições não precisam de workspaceRoot, e cada uma porque seu objeto não é um espaço de trabalho. aggrega/getSchema e aggrega/scaffoldEntity respondem a partir dos esquemas compilados no binário em execução, então um espaço de trabalho não contribui com nada para nenhuma delas — o que permite que ambas respondam em um diretório que ninguém preparou. aggrega/initialize é a terceira, e é onde você 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, sim, sobre um espaço de trabalho, e uma requisição para ela nomeia um como qualquer outra.

O estado em cache de cada espaço de trabalho é mantido separadamente, e nomear um segundo não custa nada ao primeiro. O índice do catálogo, o cache de análise e os diagnósticos de um espaço de trabalho pertencem a esse espaço de trabalho, então uma pergunta feita sobre outro lugar não remove o que um editor vem acumulando para a pasta que alguém tem aberta. Duas grafias de uma mesma raiz são um único espaço de trabalho, então um caminho que traz um . interno ou um separador duplicado chega ao mesmo estado aquecido que sua forma simples.

Declarando o espaço de trabalho para o qual você quer diagnósticos enviados por push

Os diagnósticos chegam de duas formas: você os pede, ou o daemon os envia por push. O daemon envia por push apenas para o espaço de trabalho que você declarou no handshake. Toda outra requisição responde com suas constatações em sua própria resposta e não envia nada por push.

Declare-o enviando workspaceRoot em aggrega/initialize. Isso é tudo o que a declaração faz — ela não ancora nada, e nenhuma requisição posterior é respondida com base nela.

O motivo para restringi-lo é a finalidade de um diagnóstico enviado por push. O push é o que mantém atualizada a lista de problemas de um editor enquanto alguém digita, 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 compartilha o daemon, por exemplo — encheria a lista de problemas de um leitor com constatações sobre arquivos que ele nunca abriu. Restringir o push mantém a pergunta de um chamador fora da lista de problemas de outro chamador.

O campo é opcional, e as três coisas que você pode querer dizer com ele são distinguíveis:

o que você enviapara onde vão os pusheso que o handshake reporta
nadao espaço de trabalho sobre o qual o processo foi iniciadoesse espaço de trabalho
uma raiz de espaço de trabalhoesse espaço de trabalhoesse espaço de trabalho
a string vaziapara lugar nenhum — nenhum diagnóstico é jamais enviado por pushuma raiz vazia

Não enviar nada deixa os pushes no espaço de trabalho sobre o qual o processo foi iniciado, de modo que um cliente que não declara nada recebe os diagnósticos desse espaço de trabalho. Enviar a string vazia é a declaração honesta para um chamador que não é um editor e não tem nenhuma lista de problemas a manter sincronizada: toda constatação ainda chega até ele, na resposta à requisição que a produziu.

Um espaço de trabalho declarado é resolvido exatamente como um nomeado por uma requisição, de modo que uma declaração que nomeia um caminho relativo, ou um caminho que não é um diretório, é recusada no handshake em vez de deixar os pushes apontados para algum lugar inesperado.

Raiz do espaço de trabalho e Release ativa

O daemon resolve cada espaço de trabalho que uma requisição nomeia da mesma forma que todo comando aggrega resolve um, e Configuração traz o que ancora uma raiz e em que ordem. Duas consequências importam para um cliente. Um .aggrega-config.yaml sem um bloco workspace: não ancora: ele ainda contribui com suas configurações, mas um simples arquivo de configurações não pode transformar todo diretório pai em uma raiz de espaço de trabalho. E quando nada ancora, o diretório de trabalho é usado — o daemon inicia e as operações simplesmente não resolvem nada, em vez de se recusarem a executar.

O processo também é iniciado 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 nenhuma outra: dimensiona o pool de workers, que é uma propriedade do processo e não de uma requisição, e é a declaração padrão para os diagnósticos enviados pelo daemon. Nenhuma requisição é respondida com base nela.

A configuração é igualmente a mesma cascata que todo comando lê, e Configuração é onde ela é 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 é nomeado pela primeira vez, e reutilizada em toda requisição posterior sobre ele. Um arquivo de configuração que essa cascata leria e que é um link que leva para fora do espaço de trabalho — o próprio .aggrega-config.yaml do espaço de trabalho, ou o overlay de propriedade da CI ao lado dele — não é lido, aqui como em um terminal, e nada mais do que esse arquivo teria configurado é lido no lugar dele. O que difere de um terminal é o que ainda responde. O daemon iniciado sobre um espaço de trabalho assim inicia, e informa isso uma vez em seu fluxo de erro; uma requisição que nomeia um deles é respondida da seguinte forma em qualquer caso. aggrega/releaseCandidates e aggrega/catalogIndex — as duas requisições que listam o que um espaço de trabalho contém — respondem, lendo-o sem nada configurado: os documentos do próprio espaço de trabalho são listados, nenhum diretório de catálogo é lido e o arquivo retido é nomeado em unreadLinkedFiles, quer a busca o tenha encontrado ou não. Esse nome é a forma como um cliente percebe que a configuração do espaço de trabalho leva para fora dele. Toda outra requisição que nomeia o espaço de trabalho — um build, um grafo, uma validação, a Release padrão, a configuração efetiva, uma escrita e aggrega/catalogIndex nos termos de uma Release — é decidida por essa configuração, então é recusada com o erro invalid-params que carrega E0321 — read-leads-out-of-workspace no data do erro — e a frase que nomeia o link e para onde ele leva. O handshake também responde para um espaço de trabalho assim, informando defaults como seu configSource, já que nenhum arquivo de configuração contribuiu com nada daquilo com que as listagens respondem. Remova o link, ou faça-o levar a um arquivo dentro do espaço de trabalho, e a próxima requisição lê a configuração. Abaixo dos arquivos do projeto fica a camada global: o arquivo que --config nomeia na linha de comando que iniciou o daemon, para cada espaço de trabalho que ele atende; caso contrário, o arquivo que a variável de ambiente AGGREGA_CONFIG nomeia quando está definida; e, caso contrário, o local padrão — no Windows, aggrega\config.yaml dentro do diretório que a variável de ambiente APPDATA nomeia, e nos demais sistemas aggrega/config.yaml dentro do diretório que XDG_CONFIG_HOME nomeia, recorrendo a ~/.config/aggrega/config.yaml — carregado quando presente. Os padrões embutidos ficam abaixo disso.

Operações que agem sobre uma Release recebem uma como parâmetro; o daemon não seleciona nenhuma por conta própria. Um espaço de trabalho ainda declara para qual Release aponta, e uma cascata de quatro etapas lê essa declaração: o campo de configuração build.authoring_release, depois um arquivo marcador .aggrega/active-release, depois uma heurística de Release única no espaço de trabalho, depois um último recurso baseado apenas no Aggregate. Um marcador que você escreve, portanto, tem precedência sobre a heurística, e um marcador que nomeia uma Release que não pode ser carregada recai na heurística em vez de no último recurso. Um marcador que nomeia uma Release fora do espaço de trabalho — por um caminho absoluto, por um caminho que sobe para fora da raiz ou por um link que leva para fora dela — não é lido, a menos que a configuração do seu espaço de trabalho nomeie essa Release como build.authoring_release ou como uma 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 então segue exatamente como faz com um marcador que não consegue carregar, e onde não chega a nada, trace diz por quê na linha do marcador e reason em sua frase sobre o marcador.

aggrega/activeRelease informa o que essa cascata escolhe, e é uma sugestão para um cliente, não uma configuração segundo a qual o daemon age. Pergunte ao daemon em vez de ler você mesmo as entradas da cascata: o campo de configuração e o arquivo marcador são duas de quatro entradas, então qualquer uma delas que você leia nomeia a escolha do espaço de trabalho apenas quando por acaso é a entrada que venceu. Um marcador que nomeia uma Release que não pode ser carregada é o caso mais claro — a cascata escolhe uma Release totalmente diferente, e quem lesse o marcador informaria a que falhou.

A cascata é executada quando você pergunta e não antes, o que tem duas consequências em que vale a pena confiar. O handshake continua rápido qualquer que seja o tamanho da árvore, porque não espera a varredura 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, adicione ou remova um arquivo de Release, depois pergunte de novo, e você obtém a nova resposta do mesmo daemon. Mudar a Release em que você trabalha nunca exige reiniciar o daemon — um cliente envia um release diferente na sua próxima requisição.

As operações que pesquisam todo o espaço de trabalho em vez de um único 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é o próprio diretório do arquivo contribui, com o mais próximo prevalecendo, então um arquivo YAML que seu repositório ignora não é oferecido como candidato de autocompletar e não é informado como definição ou referência. Um .gitignore que é um link que leva para fora do espaço de trabalho não é lido, então um arquivo em outro lugar da máquina nunca decide quais documentos do espaço de trabalho são pesquisados. Árvores de dependências incluídas e saída gerada ficam, assim, fora dos resultados entre arquivos sem nenhuma configuração de exclusão separada para manter — e um documento que você espera que seja encontrado mas que ignorou não aparecerá, que é o único caso que vale verificar quando uma referência parece estar faltando. 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 conforme configurados — os mesmos diretórios que um build de uma Release lê quando a configuração não dá a essa Release nenhum próprio, ou, para uma requisição que nomeia uma Release, os dessa Release — então as entidades de um diretório de catálogo são oferecidas quer um .gitignore o cubra ou não — exceto uma entidade atrás de um link que leva para fora do diretório dentro do qual as leituras de um diretório de catálogo precisam ficar, que não é lida nem oferecida.

Uma requisição que nomeia uma Release lê os diretórios de catálogo dessa Release, que são os que um build dela em um terminal lê: os próprios, onde a configuração do espaço de trabalho lhe dá alguns em workspace.releases, e, caso contrário, os catalog_dirs do espaço de trabalho. Isso abrange aggrega/build, aggrega/buildPreview, aggrega/irGraph, aggrega/releaseClosure, aggrega/resolveDependencies, aggrega/validate e aggrega/lint quando nomeiam uma Release, aggrega/attachCandidates e aggrega/attachmentContainer endereçadas a um nó do grafo de uma Release, e aggrega/connectionAtPosition, além das requisições que a próxima seção lista quando nomeiam uma. Assim, uma única sessão responde por 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 enviar nada além do caminho da Release. Uma requisição que não diz respeito a nenhuma Release específica — aggrega/catalogIndex, aggrega/entityDefinition, completion, hover e resolve sem nomear nenhuma Release, e aggrega/attachCandidates endereçada a uma entidade ou a um conjunto de rótulos — lê os catalog_dirs do espaço de trabalho. aggrega/lint sem nomear nem uma entidade nem uma Release é a exceção em um espaço de trabalho que nomeia Releases em workspace.releases: ali ele verifica o catálogo inteiro uma vez para cada Release, cada passagem sobre os diretórios dessa Release, como descreve Publicar convenções, sob demanda e a cada edição. Veja Dar a uma Release seus próprios diretórios de catálogo.

Responder nos termos de uma Release

aggrega/catalogIndex, aggrega/entityDefinition e as cinco requisições que partem de um cursor — aggrega/hover, aggrega/resolve, aggrega/completion, aggrega/findReferences e aggrega/findImplementations — não dizem respeito a nenhuma Release específica, e cada uma aceita um release opcional que a faz dizer respeito a uma. É um caminho relativo à raiz do espaço de trabalho, sujeito ao mesmo contrato que as outras requisições que aceitam uma Release lhe aplicam; um valor que não nomeia nenhum arquivo de Release, ou que nomeia um diretório, é recusado em vez de ser respondido nos termos do espaço de trabalho enquanto parece ser a resposta da Release.

O que uma Release alcança, para cada requisição aqui: os documentos do espaço de trabalho sob os diretórios de catálogo que sua pilha lê, e todo documento do espaço de trabalho que não está sob nenhum diretório de catálogo — uma Release, seu Aggregate e seu Manifest escritos ao lado dos catálogos. Um documento do espaço de trabalho sob um diretório de catálogo que apenas 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 mesma entidade, mantidas lado a lado para Releases diferentes, sejam confundidas.

  • A listagem. Nomear 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 apenas outras Releases leem fica de fora — então um espaço de trabalho que mantém uma variante de uma entidade por Release lista a única variante com que essa Release é construída, em vez de todas as variantes lado a lado. Um documento que não está sob nenhum diretório de catálogo, como uma Release, seu Aggregate e seu Manifest escritos ao lado dos catálogos, pertence à listagem de toda Release.
  • Uma busca por nome. Ao nomear uma Release, o nome é resolvido pelos diretórios de catálogo dessa Release, então um nome que várias variantes declaram é resolvido para a variante com que essa Release é construída. Um nome que seus diretórios não resolvem é recusado com uma explicação que nomeia a entrada dessa Release em workspace.releases, já que essa entrada é o que a busca leu. Uma referência de registro não aceita Release, e é recusada se receber uma: ela é lida do registro que a publica, qualquer que seja a Release nomeada.
  • Hover e ir para a definição. Ao nomear uma Release, a referência sob o cursor é primeiro resolvida pelos diretórios de catálogo dessa Release, na ordem que a configuração do espaço de trabalho lhes dá — a mesma resolução que uma busca por nome nos termos dessa Release realiza — então a entidade mostrada, e o documento aberto, é a variante para a qual esses diretórios a resolvem, mesmo onde um documento do espaço de trabalho em outro lugar declara o mesmo nome. Somente onde nenhum documento sob esses diretórios responde por ela são pesquisados os documentos do espaço de trabalho que essa Release alcança. Sem nomear nenhuma, a ordem é inversa: os documentos do espaço de trabalho são pesquisados primeiro, então uma referência à qual um documento do espaço de trabalho responde mantém essa resposta, e os catalog_dirs do próprio espaço de trabalho são consultados apenas onde nenhum documento declara o nome — que é o que encontra uma entidade que só um diretório de catálogo configurado contém, inclusive um fora da árvore do espaço de trabalho. Onde o editor mantém uma cópia não salva 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, então uma posição cai na linha que o editor mostra.
  • Autocompletar. Ao nomear uma Release, os nomes oferecidos são os que os documentos do espaço de trabalho que essa Release alcança declaram, junto com os Components e as Features que os diretórios de catálogo dessa Release declaram.
  • Referências e implementações. Ao nomear uma Release, um local em um documento do espaço de trabalho que essa Release não alcança não é informado, então uma variante mantida para outra Release nunca é listada como referência ou implementação desta.
  • O que pode se anexar a um nó do grafo. aggrega/attachCandidates endereçada a um nó do grafo de uma Release está sempre nos termos dessa Release — veja O que uma resposta de candidatos a anexação informa.

Sem nomear nenhuma, a resposta se baseia nos diretórios de catálogo do próprio espaço de trabalho, como descreve o parágrafo acima.

Alcançar um registro, e escrever

A maioria das requisições aqui responde a partir do espaço de trabalho e do que já está em cache, e não escreve nada. Algumas, nomeadas, fazem mais, e se dividem segundo dois eixos independentes: o que uma requisição alcança, e até onde vai o que ela altera.

As requisições que vão até um registro se dividem nas que leem e nas que publicam. aggrega/resolveDependencies busca o que uma Release precisa, e aggrega/build se junta a ela quando — e somente quando — seu campo autoPull lhe pede para resolver as dependências primeiro, caso em que alcança um registro e escreve o lockfile antes de renderizar; aggrega/registryUpdate percorre cada registro configurado para reconstruir o índice de busca local; aggrega/pluginAdd procura no registro configurado o plugin que uma requisição nomeia e lê suas versões publicadas para fixar uma; aggrega/registryAdd pede ao registro que registra a política de confiança que esse registro anuncia, a menos que a requisição recuse a busca ou forneça uma política própria, e aggrega/configInit pede o mesmo ao registro que está inicializando; aggrega/explainError obtém o pacote de documentação do qual lê a explicação detalhada de uma condição, uma única vez, onde o cache que todos os projetos da máquina compartilham não contém nenhuma cópia que a própria verificação de assinatura do espaço de trabalho admita — veja aggrega explain; aggrega/scaffoldEntity enviado com example ou list obtém o mesmo pacote nas mesmas condições, e uma escrita então grava o exemplo em um novo diretório do espaço de trabalho; aggrega/import busca um importer principal do registro padrão do espaço de trabalho, uma única vez, onde a máquina ainda não o tem, e, em um espaço de trabalho que não nomeia nenhuma pasta de catálogo, o snapshot publicado do catálogo que lê — veja O que uma resposta de importação informa; e aggrega/entityDefinition lê a entidade que uma referência de registro nomeia quando uma é enviada como seu name, sem escrever nada. aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts e aggrega/deprecateArtifact escrevem em um — bytes, uma assinatura ou um marcador de retirada. Uma requisição alcança um registro somente quando foi enviada para isso: uma listagem informa o que a configuração fixa, uma busca lê um snapshot offline e uma publicação pedida com dryRun calcula o que enviaria e não contata ninguém.

A regra diz respeito a quando uma operação é executada, não a qual superfície a executa. Uma operação que busca ou escreve é executada porque uma requisição a nomeou, e nunca como efeito colateral 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 digitada não alcança nenhuma rede e não reescreve nenhum lockfile, enquanto uma ação “resolver dependências” em que o usuário clica faz exatamente o que aggrega pull faz — a mesma resolução, por trás das duas superfícies, escrevendo um lockfile idêntico byte a byte e preenchendo o mesmo cache de artefatos.

Nada é perguntado. Ninguém está observando este fluxo, então a identidade é resolvida a partir de uma fonte de credenciais fornecida ou presente no ambiente, e nunca perguntando. Onde o comando de terminal teria feito uma pergunta a uma pessoa — um registro que precisa de credenciais, uma capacidade atendida por mais de um plugin de provider, o texto que uma retirada deve carregar — a requisição falha com uma mensagem que nomeia o que fornecer, em vez de ficar bloqueada esperando uma resposta que nunca chegará. Uma recusa deixa o espaço de trabalho exatamente como estava: nenhum lockfile é escrito e nenhum registro parcial é deixado para trás, e uma publicação que não conseguiu resolver uma credencial é recusada antes que qualquer byte chegue ao registro.

Algumas alterações vão além deste espaço de trabalho, e a resposta diz quais

Uma requisição nomeia um espaço de trabalho, então uma resposta que não tem nada a dizer sobre o próprio alcance é lida como sendo sobre esse espaço de trabalho. Para várias dessas requisições essa leitura estaria errada, então cada uma carrega seu escopo e um cliente deve mostrá-lo antes de agir sobre o resultado.

Publicar, assinar e retirar vão totalmente além da máquina, que é o maior alcance de qualquer coisa aqui. As outras escritas abaixo mudam o que esta máquina resolve; estas mudam o que qualquer pessoa que resolva a partir desse registro faz. Os bytes publicados são o que todo consumidor desse registro recebe, e republicar conteúdo diferente sobre uma tag é recusado em vez de oferecido, então nenhuma requisição aqui desfaz uma publicação — a resposta é publicar uma nova versão. Uma assinatura e um marcador de retirada são anexados ao lado do artefato em vez de substituí-lo, então os próprios bytes ficam intactos; mas quem buscar o artefato depois os busca também, e nenhum dos dois pode ser recolhido de quem já o tem. Uma retirada é, das três, a mais fácil de interpretar mal: a versão continua podendo ser buscada, enquanto uma retratação em que um espaço de trabalho confia a tira do que uma resolução ali vai escolher.

A assinatura usa credenciais, e vale a pena saber de onde elas vêm antes de conectar um cliente. A assinatura sem chave resolve um token de identidade, nesta ordem, a partir de identityToken na requisição, depois de AGGREGA_IDENTITY_TOKEN no ambiente do daemon, depois do endpoint OIDC do GitHub Actions presente no ambiente onde houver um acessível, depois de SIGSTORE_ID_TOKEN. Quando nenhum deles fornece um token, a operação é recusada e nomeia o que enviar; ela nunca abre um navegador, porque não há ninguém para olhar para ele. A assinatura com chave é a alternativa offline, e uma requisição não nomeia nenhum caminho de chave: o que uma requisição lê fica dentro do espaço de trabalho que ela nomeou, e uma chave privada nunca é mantida dentro de um espaço de trabalho, então a chave vem, em vez disso, do bloco signing: da própria configuração desse espaço de trabalho. Veja aggrega sign para os dois modos de assinatura e o que cada um contata.

Cada uma das quatro respostas carrega reach, que contém registries — cada host de registro que a chamada endereçou, cada um nomeado uma vez, na ordem em que a chamada o endereçou pela primeira vez, então um lote de assinatura ou um arquivo de lote cujas referências abrangem vários registros nomeia cada um deles — e beyondThisMachine, que é derivado do que a chamada de fato anexou e não do que ela pediu: verdadeiro exatamente quando ela enviou conteúdo ou anexou uma assinatura, uma data de publicação ou um marcador de descontinuação, e falso para uma execução de teste 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á carregava uma assinatura que é verificada. Uma execução de teste ainda nomeia o destino que teria endereçado. Mostre-o antes de agir sobre o resultado.

Registrar ou remover um registro escreve, por padrão, a configuração compartilhada por todos os espaços de trabalho da máquina. Um registro e as identidades em que você confia nele costumam ser os mesmos onde quer que você trabalhe, então é para lá que a entrada vai, a menos que a requisição envie workspace: true. Vale a pena dizer a consequência com clareza: aggrega/registryAdd e aggrega/registryRemove mudam aquilo por meio do qual todo projeto dessa máquina resolve, inclusive projetos que ninguém nesta sessão nomeou. As duas respostas carregam scope, com o configFile que foi escrito e machineWide dizendo se é o compartilhado. A remoção é a mais delicada das duas, porque adicionar de novo não é o mesmo ato — a política de confiança que estava fixada se foi, e um registro posterior fixa o que quer que o registro anuncie nesse momento.

Inicializar uma configuração escreve, por padrão, esse mesmo arquivo compartilhado, e pelo mesmo motivo. aggrega/configInit registra um registro e sua política de confiança, que são ferramentas de toda a máquina, então, sem substituição, escreve a configuração por meio da qual todo projeto da máquina resolve — e alcança esse registro uma vez para ler a política que ele anuncia. Sua resposta carrega o mesmo par scope que os dois métodos de registro carregam. Ela difere deles em um aspecto em que vale a pena confiar: ela recusa em vez de sobrescrever um arquivo de configuração existente, então não pode substituir uma configuração a partir da qual alguém está trabalhando, a menos que a requisição envie force. Congelar é o caso oposto: aggrega/configCapture não aceita nenhuma substituição, sempre escreve o próprio arquivo de configuração do projeto e não alcança nenhum registro, então nada do que faz é visível para outro projeto. Veja O que uma escrita de configuração deixa para trás.

🔴 Adicionar ou remover um plugin de extensão de comandos escreve, por padrão, esse mesmo arquivo compartilhado, e este é o caso para ler com atenção. aggrega/pluginAdd e aggrega/pluginRemove aceitam um type, e o tipo decide para onde vai a escrita quando nenhuma substituição é enviada. Uma entrada provider, governance, linter ou importer molda o build de um projeto, então vai para a própria configuração desse projeto. Uma entrada cli é uma ferramenta de toda a máquina, então uma adição do tipo cli que não nomeia nem global nem workspace registra o comando no arquivo de configuração global por meio do qual todo espaço de trabalho desta máquina resolve — o comando passa a ser um comando aggrega de nível superior para todo projeto dessa máquina, inclusive projetos que ninguém nesta sessão nomeou, e retirá-lo é uma remoção separada, não um desfazer. Envie workspace: true para mantê-lo local. As duas respostas carregam scope, com o configFile que foi escrito e machineWide dizendo se é o compartilhado, derivado do arquivo para o qual a escrita foi resolvida. Uma adição também alcança o registro em que pesquisou, então está nos dois eixos ao mesmo tempo. Veja O que uma alteração de plugin informa.

As outras duas requisições de plugin escrevem apenas dentro do espaço de trabalho. aggrega/pluginSync escreve o arquivo de entidade Plugin que a requisição nomeia, e aggrega/pluginGenCatalog escreve as entidades geradas sob o outputDir que a requisição nomeia — ambas dentro do espaço de trabalho que a requisição nomeou, ambas recusando um destino que seja absoluto ou que se resolva fora dele, e nenhuma visível para outro projeto. aggrega/pluginGenCatalog lê seu módulo e seu overlay de onde quer que você os tenha selecionado, o que não amplia onde ele escreve: os dois são resolvidos por regras diferentes, então uma geração pode ler um módulo que você construiu em qualquer lugar enquanto as entidades que ela produz ainda vão parar dentro do espaço de trabalho. aggrega/pluginGenCatalog com dryRun não escreve nada e devolve o conteúdo em vez disso.

Fixar uma entidade também escreve apenas dentro do espaço de trabalho, e alcança os hosts que suas fontes nomeiam. aggrega/pin escreve o entity.lock ao lado da entidade que a requisição nomeia, que é um caminho dentro do espaço de trabalho, e preenche o cache de conteúdo do espaço de trabalho com as fontes que buscou; nada do que escreve é visível para outro projeto. Ele sai para resolver cada fonte remota que a entidade nomeia — um repositório de charts, um host Git, uma URL — que é o mesmo alcance que aggrega/resolveDependencies tem para as fontes que uma Release consome. aggrega/resolveDependencies e aggrega/publishEntity enviadas com pinSources executam esta mesma etapa, então cada uma delas também escreve ao lado das entidades que fixa; uma publicação que fixa, portanto, alcança o espaço de trabalho além do registro. Uma publicação que não fixa não escreve nada ao lado da entidade, e ainda assim alcança esses hosts: comparar o lock com o que a etapa registraria significa buscar cada fonte remota que a entidade escreve por extenso.

Instalar a skill do assistente fica dentro do espaço de trabalho, a menos que a requisição envie global. aggrega/skillsInstall escreve a pasta de skills de projeto de cada assistente nomeado dentro do espaço de trabalho que a requisição nomeou, e nada do que escreve ali é visível para outro projeto; o scope da sua resposta carrega machineWide false. Com global: true, ele escreve em vez disso a pasta por usuário de cada assistente sob o diretório home, que esse assistente lê em todo projeto da máquina, e machineWide é true. Em ambos os casos, não alcança nenhum registro nem nenhuma rede.

Remover uma credencial armazenada vai mais longe do que qualquer outra coisa aqui que para nesta máquina. aggrega/logout altera o armazenamento de credenciais, e esse armazenamento é compartilhado não só por todo projeto da máquina, mas por toda outra ferramenta que se autentica nos mesmos registros — então uma credencial removida por meio de uma sessão some para todos eles, e aggrega/registryList vai informá-la como ausente também em todo outro espaço de trabalho. Sua resposta carrega scope com machineWide, que é sempre true: esse armazenamento não tem nenhuma forma restrita ao espaço de trabalho para a qual se resolver, então não há nenhuma substituição para enviar nem nada a que uma requisição possa aderir. scope deliberadamente não nomeia nenhum arquivo, ao contrário das escritas de configuração acima. O armazenamento delega a qualquer auxiliar de credenciais ou chaveiro do sistema operacional que a máquina tenha configurado, então a remoção frequentemente é atendida por algo que nem é um arquivo, e nomear um caminho apontaria você para um local que a remoção não necessariamente tocou.

A remoção não é o inverso da autenticação, e um cliente não deve oferecê-la como tal. Esta superfície remove uma credencial e não obtém nenhuma: recuperar uma credencial significa autenticar-se de novo com aggrega login em um terminal, porque armazenar uma exige um segredo digitado por uma pessoa e ninguém está observando este fluxo. Então um “sair” que um cliente oferece é, a partir daqui, de mão única. O que separa as duas operações é se a operação precisa obter algo de quem a conduz — uma remoção carrega seu único valor na requisição, enquanto obter uma credencial não — e não se há uma pessoa envolvida, já que uma pessoa escolheu ambas.

Liberar conteúdo do 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 compartilhados por todo projeto da máquina, então aggrega/cachePrune, aggrega/cacheEvict e aggrega/cacheClear podem remover conteúdo de que outro projeto depende. Cada remoção carrega o reach da classe de onde veio, e cada resposta carrega scope.machineWideClasses. aggrega/cacheStatus carrega o mesmo alcance em toda classe mesmo sem alterar nada, porque um cliente que decide se vai liberar espaço precisa dele antes de agir.

Atualizar o índice de busca é o caso inverso. aggrega/registryUpdate alcança cada registro configurado, e o que ele escreve vai parar sob o diretório de cache configurado deste próprio espaço de trabalho — então não altera nada por meio do qual outro projeto resolve. indexRoot na resposta nomeia esse diretório.

Uma atualização parcial responde em vez de falhar. Uma requisição que nomeia um registro cuja atualização falhou é um erro, porque não há resposta a dar. Uma requisição que atualiza cada registro configurado tem sucesso mesmo onde alguns deles, ou todos, falharam: os atualizados foram indexados e escritos, failed nomeia os demais, e cada host carrega seu próprio erro. Leia failed em vez da presença de um erro.

Se um registro pôde ser alcançado é uma chave, não uma leitura da mensagem. Um host que falhou carrega unreachable: true onde o registro nunca foi alcançado — seu nome não foi resolvido, uma conexão com ele foi recusada ou não pôde ser aberta, ou uma conexão segura com ele não pôde ser estabelecida — e a recusa de uma requisição que nomeia um registro carrega a mesma chave em seu data. Um registro que foi alcançado e falhou, com uma listagem que se repetia ou um status de erro, não a carrega em nenhum dos dois casos, e seu error, ou a mensagem da recusa, diz o que ele respondeu. A chave é lida da própria falha, então não depende de como o resolvedor desta máquina formula uma falha, e é definida apenas onde a falha mostra que o registro nunca foi alcançado: uma falha que não mostra nada em nenhum sentido, como um limite de tempo esgotado sem registro de qual etapa interrompeu, é informada sem ela. Indique um registro como não alcançado com base na chave, e mostre o erro como motivo.

A linha de comando informa essa mesma varredura como uma saída diferente de zero, e o tipo de leitor que você é decide quanto vale essa saída. Para uma pessoa diante de um terminal, ela não é o relato completo: aggrega registry update imprime quantos dos registros selecionados indexou, o que cada um encontrou, quais não indexou e onde o índice foi escrito — então o resumo diz o que aconteceu e o status de saída diz apenas se tudo teve sucesso. Para um script, é o relato completo, porque esse comando não oferece nenhum modo de saída estruturada, então seu status de saída é o único veredito legível por máquina disponível. É por isso que as duas superfícies respondem de forma diferente à mesma varredura parcial e ambas estão certas: esta entrega failed a um chamador estruturado e tem sucesso, enquanto a linha de comando tem um único bit para gastar e o gasta em “algum registro ficou de fora”.

Acompanhar uma operação longa

A maioria das requisições aqui responde a partir do que já está em disco e responde de imediato. Algumas fazem primeiro um trabalho real — resolver as dependências de uma Release, fixar suas entradas externas, publicar, assinar, retirar — e o chamador espera. Essas informam o que estão fazendo enquanto fazem, e isso é ativado explicitamente por requisição.

Ativar exige duas etapas, nesta ordem.

  1. Declare a capacidade no handshake e espere a resposta. Envie capabilities.window.workDoneProgress: true em aggrega/initialize. Não envie mais nada até que essa resposta tenha chegado: as requisições são atendidas de forma concorrente, então uma requisição escrita antes de o handshake responder pode estar sendo executada junto com o handshake que deveria negociar por ela. Todo cliente já deve essa ordem ao protocolo; esta é mais uma coisa que depende dela.
  2. Coloque um token nos params da requisição. Adicione workDoneToken aos params da requisição sobre a qual você quer receber informações. O valor é você quem escolhe — uma string ou um número — e é o que liga as notificações a essa chamada. Gere um novo para cada chamada.

A notificação. Cada uma é $/progress com params.token definido como o seu token e params.value carregando um payload:

value.kindcarregaquando
begintitle — o que está acontecendo, em uma frase que você pode colocar diante de um leitoruma vez, quando o trabalho começa
reportmessage — uma linha do relato que a própria operação faz de si mesmaqualquer número de vezes, à medida que a operação as escreve
endnada além do tipouma vez, quando o trabalho termina

Correlacione pelo token, nunca pelo id da requisição. Uma notificação não carrega nenhum id — ela não é resposta a nada — e o token é a única coisa nela que remete à sua chamada. Isso é deliberado: em muitos clientes, o id da requisição pertence ao transporte e nunca chega ao código que emitiu a chamada, enquanto o token é um valor que esse código já tem.

Um report carrega o próprio texto do compilador. A mensagem é uma linha que a operação escreveu enquanto trabalhava, repassada com os espaços ao redor removidos 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 ser informada como mensagem vazia. Então um cliente mostra o que recebe tal como está. É a mesma propriedade que os próprios diagnósticos da resposta têm: uma condição mantém uma única redação, por mais superfícies que a informem.

Uma etapa pela qual a operação espera também é um report. Quando a operação entra em uma etapa pela qual espera — ler um registro, buscar um artefato, compilar um plugin —, um report traz o nome da etapa, nas palavras que a linha de comando mostra ao lado do seu indicador de atividade para a mesma etapa. Somente as etapas iniciadas entre o begin e o end são informadas.

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 em partes é informada assim que fica completa — então uma mensagem nunca é meia frase.

Não há fração nem porcentagem, e isso não é uma omissão à espera de trabalho. As operações que informam 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 envia — então qualquer fração seria inventada. Desenhe um indicador indeterminado e mostre a message mais recente.

Os frames chegam antes da resposta e nunca depois dela. Um begin chega assim que o trabalho de fato começou, então uma requisição recusada por seus params — um caminho absoluto, um campo obrigatório ausente — não produz nenhuma notificação, apenas seu erro. O end chega antes da resposta, e se a operação teve sucesso consta na resposta em vez de ser repetido no end.

Interromper o trabalho é uma notificação separada. Envie $/cancelRequest com o id com que você enviou a requisição. O token não tem nenhum papel no cancelamento, e cancelar não suprime os frames já enviados.

Quais requisições informam, e o que esperar das demais

Exatamente estas informam: aggrega/resolveDependencies, aggrega/pin, aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts, aggrega/deprecateArtifact.

Duas coisas valem para cada uma delas, e ambas são o motivo de ela estar na lista: ela alcança um registro ou uma URL remota em seu nome, então quanto tempo leva é determinado por algo fora da máquina; e ela já escreve o próprio relato de si mesma à medida que avança — o relato que uma pessoa que observa um terminal lê. Então o informe entrega a você esse mesmo relato, em vez de um segundo composto para a transmissão, e nada do que a operação faz precisou mudar para produzi-lo.

Toda outra requisição aceita um token e não envia nada. Enviar um é inofensivo, e não um erro: ele é aceito, nenhuma notificação chega e a resposta é exatamente a que você teria obtido sem ele. Então um cliente pode anexar um token ao que quiser e simplesmente não desenhar nada quando nada chegar.

🔴 Não interprete o silêncio como “esta é instantânea”. A maioria das demais de fato responde a partir do que já está em disco — uma validação, um hover, um autocompletar, um grafo, uma listagem do cache, uma leitura de configuração — mas não todas: atualizar o índice de um registro, adicionar um plugin, uma verificação antes da publicação e a primeira explicação de um código em uma máquina que não tem nenhuma documentação que o espaço de trabalho possa ler alcançam todas um registro, e compilar uma Release é trabalho real. Essas levam o tempo que levam e hoje não informam nada. Mostre um indicador indeterminado para qualquer requisição que você esteja disposto a esperar, e trate as notificações como um detalhe que você obtém quando está disponível, e não como aquilo que lhe diz que há trabalho em andamento.

Duas recusas

Ambas são erros invalid-params e ambas nomeiam o que fazer, porque um token que silenciosamente não fizesse nada deixaria você esperando por um fluxo que nunca viria.

  • Um token de uma sessão que não declarou nenhuma capacidade window.workDoneProgress é recusado, nomeando a capacidade a declarar. Declare-a no handshake, ou deixe o token de fora.
  • Um token que não é nem uma string nem um número é recusado, nomeando as duas formas. Um token ausente, e um null explícito, não são recusas — ambos significam que você não pediu nenhum informe.

Reconhecimento do lockfile

O daemon verifica o desvio de um lockfile a cada aggrega/irGraph, em relação à Release que essa requisição nomeou, apresentando o desvio como um aviso não bloqueante. O aviso nomeia o comando que reescreve esse lockfile com a Release nele, escrito como a requisição o enviou — aggrega pull --release seguido do release que você enviou, que é como se escreve em um terminal na raiz do espaço de trabalho. aggrega/irGraph exige que um lockfile esteja presente. Não há verificação separada na inicialização: uma requisição diz de qual Release se trata, então o veredito é calculado para essa Release quando é pedido, e não uma única vez para uma Release escolhida de antemão.

Um aviso de desvio vai embora quando seu lockfile vai embora. O aviso é publicado no lockfile em relação ao qual foi emitido, e um lockfile que não está mais lá não tem mais fixações que possam ter se desviado — o comando que o aviso nomeia escreveria um novo arquivo em vez de reparar o antigo. Então toda requisição que encontra o lockfile ausente retira o aviso antes de recusar com o erro de lockfile ausente: aggrega/irGraph, aggrega/releaseClosure, aggrega/build, aggrega/buildPreview, aggrega/attachCandidates e aggrega/attachmentContainer consultadas 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. Ela vem da primeira dessas requisições que tomar conhecimento da exclusão, então um cliente que informa a exclusão e depois pede qualquer coisa sobre essa Release tem o aviso removido sem pedir especificamente o grafo. Um lockfile que ainda está presente e ainda desviado mantém seu aviso ao longo de cada uma dessas requisições. aggrega/invalidate nomeando o lockfile descarta o que o daemon mantém para ele, mas não envia nada; é a requisição seguinte que informa o cliente. E um lockfile que o daemon nem consegue examinar — um cujo diretório ele não pode ler, por exemplo — não retira nada, porque ele ainda pode estar lá e o aviso ainda pode ser verdadeiro.

aggrega/build e aggrega/buildPreview também exigem um, e prendem a Release a ele em vez de avisar — eles renderizam com a postura de uma superfície que emite um artefato, então um lockfile que não corresponde mais ao que a Release resolve os interrompe onde, em uma inspeção, apenas geraria um aviso. Uma Release sem lockfile é recusada com o erro de lockfile ausente. A exceção é um build cujo campo autoPull lhe pede para resolver as dependências primeiro: esse build 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 escrevê-lo e não escreve nenhum lockfile que essa verificação recuse.

Um lockfile que existe mas não registra nenhum digest para um plugin não interrompe o grafo — um lockfile ausente, sim. São duas condições, e só a segunda leva a uma recusa. aggrega/irGraph não prende os bytes que resolve aos seus digests registrados: uma fixação que ele não consegue verificar é informada em vez de recusada, e o grafo é desenhado com a constatação no painel Problems, já que um editor que se recusa a desenhar o grafo deixa o leitor sem nada, enquanto um relatório lhe deixa algo sobre o que agir. Em outros lugares, o plugin também é executado, com um aviso dizendo que nada verificou seus bytes. O que aggrega/irGraph recusa é o lockfile ausente: ele para antes de resolver qualquer coisa e responde com o erro de lockfile ausente, nomeando o lockfile que procurou e a Release, então um cliente pode 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 coisas separadas importa, porque um grafo desenhado é uma imagem sobre a qual um leitor depois raciocina, e um grafo construído a partir de bytes que nada verificou é desenhado exatamente como um verificado, com a constatação em algum lugar para onde o leitor não está olhando. Então um grafo não é um veredito sobre os bytes por trás dele — aggrega/build e aggrega/buildPreview são as superfícies que prendem uma Release aos seus digests registrados, parando onde a inspeção apenas informa.

aggrega/validate, quando uma requisição nomeia uma Release, lê o lockfile dessa Release apenas para suas fixações e seus avisos de descontinuação — e não lê nenhum para uma entidade de catálogo que verifica como entidade individual, assim como a linha de comando não lê nenhum. Ele não prende os plugins que executa aos digests registrados, e não reconstrói a partir do lockfile o conjunto de anexações dos plugins de transformação — ele valida em relação à configuração do espaço de trabalho tal como está diante de você, que é o que um editor tem de fazer enquanto você está editando essa configuração. aggrega validate e aggrega build fazem ambas as coisas, e continuam sendo as superfícies de referência para um veredito sobre um espaço de trabalho com commit.

Seus avisos de descontinuação cobrem os dois lugares onde uma retirada é registrada. Um marcador em uma referência fixada fica no lockfile; um marcador em um plugin anexado em um papel que retorna um veredito de aceitação ou rejeição — um anexo plugins.governance em ir-verdict ou render-verdict, ou um anexo plugins.linter — fica no registro de confiança de plugins ao lado dele, então a validação lê ambos e nomeia cada referência retirada e cada plugin retirado como um alerta no início do Aggregate, com as palavras que aggrega build imprime. Um aviso não altera nenhum veredito. Um registro de confiança que existe e não pode ser lido é informado como erro no lugar da validação, em vez de ser lido como um que não registra nada. aggrega/releaseClosure informa o mesmo conjunto em seu deprecations.

Onde fica o lockfile de uma Release

Toda resposta que nomeia uma Release nomeia também seu lockfile, então um cliente nunca precisa deduzir o caminho. aggrega/activeRelease o carrega como lockfile ao lado de release, aggrega/releaseCandidates como o mapa lockfiles ao lado de releases, e o erro de lockfile ausente como lockfile em seu data. Cada um é o arquivo que aggrega pull --release <release> escreve e aggrega build lê, e o arquivo que toda requisição acima verifica — então um cliente que observa o lockfile de uma Release, para perceber que ele é escrito, reescrito ou excluído, observa o arquivo 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 nomeada com qualquer outra extensão mantém seu nome inteiro, então o lockfile de release.rel é release.rel.lock. Leia o caminho da resposta em vez de compô-lo a partir dessa descrição, e os dois não podem divergir.

As referências externas que uma renderização solicita

Uma renderização pode solicitar conteúdo de uma URL remota — o schema de valores de um chart com uma referência remota, por exemplo. As entradas externas ficam congeladas em toda renderização que este daemon realiza em resposta a uma requisição que só pediu para ser informada de algo. Uma referência que o lockfile da Release fixa é servida a partir do store endereçado por conteúdo, o que é uma leitura de conteúdo que já está em disco e não um download, e é verificada em relação ao que o lockfile registra antes de seus bytes serem servidos — assim, uma renderização aqui vê o que uma build vê e emite os avisos que uma build emite. Uma referência que o lockfile não fixa é recusada em vez de baixada: adquiri-la significaria acessar uma rede e gravar um blob no store, e uma sessão não faz nenhuma das duas coisas em uma requisição que só pediu para ser informada de algo. Essa é a regra de Acessar um registry e gravar lida do lado da renderização, e ela vale seja qual for a forma como se chegou a essa renderização.

A requisição que existe para fixar é a exceção, e é a mesma exceção que a regra do registry já prevê. aggrega/resolveDependencies é solicitada a adquirir, então a renderização que ela realiza para descobrir quais referências esta Release consome acessa a rede e grava o que fixa — e é isso que faz de seu resultado um lockfile, e não um relatório. Nenhuma renderização que uma requisição de grafo ou de build realiza para si mesma faz nada disso.

Uma build solicitada a resolver primeiro é respondida a partir dessa mesma renderização, e é por isso que ela renderiza a Release uma única vez. A resolução já renderizou aquilo de que a build trata, em relação aos pins que acabou de gravar e sob as verificações que uma build executa, então a build apresenta essa renderização em vez de realizar uma segunda — e a aquisição continua pertencendo à resolução, e não à build. Somente uma renderização que terminou é usada dessa forma: quando uma resolução fixou suas dependências mas não conseguiu terminar de descobrir as referências externas, a build renderiza por conta própria em relação aos pins que de fato foram gravados, e uma referência não fixada é recusada e relatada ali exatamente como em uma build que não resolveu nada.

A recusa é relatada em vez de absorvida, porque nada em um resultado diz qual referência estava faltando nele. Com os providers que este binário inclui, o provider que solicitou a referência devolve a recusa, então uma renderização que chegou a uma referência recusada não se completa. Por isso, cada referência recusada chega como uma entrada própria na camada aggrega-build, nomeando 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 ainda é retornado, com o mesmo status que tem o aviso de drift acima — e são atribuídas ao Aggregate no início do arquivo, porque uma referência que uma renderização solicitou não nomeia nenhuma chave escrita por um autor. Elas viajam na mesma publicação que os avisos próprios da renderização, que substitui essa camada por inteiro, então uma referência que você fixar em seguida deixa de ser relatada sem que nada precise apagá-la. Uma renderização totalmente fixada não diz nada sobre isso. Veja O que uma entrada de diagnóstico contém para a forma que cada entrada assume.

Em aggrega/irGraph, isso depende de a etapa de renderização ser executada. A requisição de grafo pula a renderização a menos que --build-on-inspect, ou a chave serve.build_on_inspect que ele sobrescreve, a ative; com a opção desligada, nada solicita uma referência externa e não há nada a recusar. Ativá-la é o que traz para uma sessão do editor tanto os avisos próprios da renderização quanto estes.

Em que uma sessão difere do mesmo congelamento na linha de comando. aggrega build também congela as entradas externas em uma execução de teste, e uma referência não fixada se comporta da mesma forma nas duas superfícies: ela é relatada como uma constatação que nomeia a referência, e então a renderização é interrompida, porque o provider que a solicitou devolve a recusa. O que difere é o novo download. Na linha de comando, uma referência fixada cuja cópia armazenada sumiu é baixada novamente pelo seu digest registrado; a renderização que responde a uma requisição de grafo ou de build não baixa nada novamente, porque essa renderização não acessa nenhuma rede, então não pode voltar a buscar uma referência fixada que o store não contém mais — e tal referência não está entre as recusas descritas acima, que nomeiam o que o lockfile não fixa. Pedir a uma sessão que fixe é o que a recupera: as requisições citadas acima acessam a rede e repõem os bytes que faltam. Veja aggrega pull para saber o que a fixação baixa e registra.

O que uma execução recusada ainda informa a você

Uma requisição 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 carrega nenhum corpo de resultado. Elas chegam a você da mesma forma que chegam em uma execução que terminou: como uma publicação de diagnósticos na camada aggrega-build, descrita em O que uma entrada de diagnóstico contém. Assim, um cliente que trata uma recusa lê o envelope para saber o que mudar e 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, então ela chega aos dois, como descreve a próxima seção.

Essa publicação acontece quer a execução tenha chegado ao fim, quer não. Uma execução que para no meio do caminho ainda encontrou tudo o que vem antes do ponto em que parou, e um leitor que perdesse essas constatações teria de executar de novo para vê-las — por isso os avisos são publicados a partir do que a execução alcançou, e a recusa é retornada depois. É o mesmo conjunto, com a mesma fidelidade, posicionado nas mesmas chaves de autoria: uma recusa não rebaixa uma constatação a uma frase. As referências externas recusadas viajam nessa mesma publicação, pelo mesmo motivo e pelo mesmo caminho.

O que a limita é até onde a execução chegou, e não o que a camada pode carregar. Uma recusa de uma das verificações executadas antes de o compilador iniciar — não foi possível resolver o fechamento da Release, o Manifest mapeia um tipo para uma receita que não o implementa, o lockfile não corresponde mais àquilo em que a Release se resolve, uma entrada fixada no cache não corresponde mais ao digest registrado para ela e nenhum diretório do catálogo contém os bytes fixados — não tem avisos a publicar, porque nenhum havia sido levantado ainda. A camada então não carrega nada em vez de algo desatualizado; e uma execução que não chegou a nomear um documento não publica nada, deixando o que já está na sua superfície de problemas exatamente como estava em vez de apagar entradas sobre as quais não soube nada.

Uma recusa emitida durante a renderização

Uma Release que o compilador recusa durante a renderização — um Workload que nomeia um slot que seu Component não declara, uma asserção que falha, um template que não pode ser avaliado, uma realização que não fornece o que deve fornecer — é relatada onde aponta e com as palavras do compilador, em toda requisição que a renderiza: aggrega/build, aggrega/buildPreview e aggrega/irGraph com a etapa de renderização ativada. A resposta é um envelope de erro com o código -32603, cujo message é a recusa com cada causa abaixo dela, nas palavras que a linha de comando imprime para a mesma build: o nó que está sendo renderizado, depois o que nele recusou, cada causa após aquela que ela explica — precedida, quando a recusa nomeia uma condição registrada, pelo código curto dessa condição, como é toda recusa que nomeia uma. Seu data nomeia o documento para o qual a recusa aponta como file, e o intervalo da chave nele como line, column, end_line e end_column, ao lado de code e shortCode da condição; uma recusa que não nomeia nenhuma chave, ou uma que o documento não contém, carrega 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 severidade error que carrega o keyPath próprio da recusa e o message do envelope sem o código curto na frente, e — quando a recusa nomeia uma condição registrada — code, shortCode e codeDescription dessa condição, com o código curto viajando ali em seu próprio campo. Ela viaja na única publicação que carrega os avisos que a execução levantou antes de parar, então substitui a camada como eles: a próxima execução da Release que renderiza publica a camada sem ela, e o documento em que ela estava é publicado vazio, que é o que a remove da sua superfície de problemas.

O lugar para onde uma recusa aponta é o que a própria recusa nomeia, e nada mais preciso. As verificações de um Workload julgam o documento que seu template produziu, e um template pode escrever linhas que nenhum autor escreveu — um loop, uma condição, um texto importado de um arquivo ou de uma biblioteca —, então uma linha do Workload renderizado não corresponde a uma linha da Recipe. Por isso, uma recusa sobre um Workload é colocada na chave workload da Recipe, e os caminhos que ela nomeia dentro do documento renderizado permanecem na sua mensagem. Uma asserção que falha é colocada em sua própria chave sob assertions na Recipe ou na FeatureRecipe que a declara; uma asserção que um Component ou uma Feature declara é levantada antes de haver um documento disponível para nomear, e é colocada na chave kind: do Aggregate. Uma recusa de uma etapa que nomeia um documento mas nenhuma chave é colocada na chave kind: desse documento.

Uma recusa que reúne várias constatações é publicada constatação por constatação. A composição do grafo a partir do qual a renderização trabalha recusa com todas as violações que encontrou em uma única recusa — uma entrada que nomeia um destino ao qual nada responde, duas conexões de um componente com o mesmo alias — e a linha de comando imprime cada uma como um diagnóstico próprio, sob 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 a Release a escreveu, o Aggregate onde o Aggregate o fez —, com suas próprias palavras e seus próprios códigos. O message da resposta carrega todas as constatações, e seu data nomeia para onde aponta a primeira.

Um valor que um autor declarou sensível é ocultado aqui exatamente como a linha de comando 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 onde a recusa é levantada — <redacted> em seu lugar —, então esta resposta, esta entrada e o terminal o carregam com as mesmas palavras; o que uma recusa diz sobre um valor declarado explica como, e quais recusas ficam fora disso.

Uma recusa de uma verificação executada antes da renderização não é isso. As verificações listadas acima respondem como descreve O que uma execução recusada ainda informa a você. Uma asserção que um Component ou uma Feature declara, e uma recusa sobre o grafo composto, ficam entre os dois: cada uma é levantada antes da renderização, por toda requisição que resolve o grafo de uma Release, então aggrega/irGraph a responde e a publica como acima também com a etapa de renderização desativada; aggrega/releaseClosure, aggrega/attachCandidates e aggrega/attachmentContainer consultados sobre um nó do grafo, e aggrega/connectionAtPosition, a respondem com o mesmo envelope e não publicam nada, porque não possuem nenhuma superfície de problemas.

Códigos de erro

As respostas usam os códigos de erro padrão do JSON-RPC mais uma faixa no nível da aplicação na banda 1xxx. Um cliente de editor pode ramificar pelo código sem analisar a mensagem.

  • 1001 file-not-validated (arquivo não validado) — o daemon não tem nada para o arquivo, tal como ele está agora, a partir do qual a requisição possa responder: nenhuma análise dele ou, para aggrega/diagnostics, nenhuma análise dele ou nada guardado para o arquivo que seja a resposta de uma validação para o texto que o daemon tem agora. Envie aggrega/validate para ele e pergunte de novo.
  • 1003 lockfile-absent (lockfile ausente) — a Release que a requisição nomeou não tem lockfile, e a operação solicitada precisa de um.
  • 1004 entity-not-resolvable (entidade não resolvível) — o nome não correspondeu a nenhuma entidade em nenhum nível do catálogo, nem na Release que a requisição nomeou; ou a referência de registry enviada como nome não pôde ser lida como uma entidade, e a mensagem nomeia a condição que diz por quê; ou o lockfile da Release é um link que leva para fora do workspace, o que é recusado antes que qualquer coisa o leia, com data nomeando o lockfile e a Release e a mensagem começando com o código curto da condição, E0321 — veja o limite do workspace.
  • 1005 shutting-down (desligando) — o daemon está sendo esvaziado após uma notificação de desligamento e recusa novas requisições. Não tente de novo contra o mesmo subprocesso.
  • 1006 validation-in-flight (validação em andamento) — uma validação do arquivo está em execução e não terminou dentro do prazo que a requisição em espera lhe concedeu. Pergunte de novo em breve e não envie nada.

1002 não está alocado, e está disponível para a próxima condição que precisar de um código.

File-not-validated e validation-in-flight relatam estados opostos, e a ação que cada um pede também é oposta. File-not-validated significa que o daemon não tem nada para o arquivo, tal como ele está agora, a partir do qual a requisição possa responder — nenhuma análise dele ou, para aggrega/diagnostics, nenhuma análise dele ou nada guardado para o arquivo que seja a resposta de uma validação para o texto que o daemon tem agora: envie aggrega/validate e pergunte de novo. Uma validação cancelada no meio do caminho deixa um arquivo nessa situação, porque não armazena 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 valendo enquanto o texto for aquele que ela verificou. As constatações que o daemon envia sobre um arquivo que ele mesmo leu do disco — um lockfile que divergiu, uma Release que não carrega — não são uma validação do texto que você tem, então também não respondem a esta requisição. Duas validações de textos diferentes enviadas em pouco intervalo também podem deixar você nessa situação, quando aquela cujo texto o daemon manteve terminou primeiro: a requisição é recusada embora esse texto tenha sido verificado, e validar de novo a responde. Ele é formulado em termos da análise e não do arquivo porque um buffer que nenhum parser vai ler está exatamente nessa posição — a validação foi executada e relatou o que encontrou, e ainda não há análise a partir da qual responder. Validation-in-flight significa que uma validação dele está em execução e não terminou dentro do prazo que a requisição em espera lhe concedeu: pergunte de novo em breve e não envie nada, porque o estado de que você precisa já está a caminho e uma segunda validação só acrescentaria trabalho. Ler os dois como uma única condição leva um cliente a enviar uma validação justamente no caso em que enviar uma é o passo errado. As duas bandas significam coisas diferentes para um cliente: um código 1xxx nomeia um estado do workspace sobre o qual o usuário pode agir — validar o arquivo, gerar o lockfile —, enquanto um código padrão como invalid-params nomeia uma requisição malformada, que o cliente corrige, e não o usuário. Um valor release presente mas malformado — absoluto, ou que se resolve fora da raiz do workspace — cai na segunda banda: não é o workspace que está em um estado que o usuário precisa reparar, é a requisição. Omitir release não está em nenhuma das bandas, porque não é um erro; isso seleciona a mais restrita das duas respostas descritas em Validação ao vivo.

Um erro pode carregar um objeto data, e cada chave nele nomeia uma coisa e somente ela. file é o documento de origem de que trata a falha — o documento sendo validado, a Release cujo carregamento falhou, o documento do workspace que declara um nome que nada resolveu, ou o documento para o qual uma recusa levantada durante a renderização aponta — e é dentro dele que os eventuais line e column que o acompanham localizam uma posição. Esses dois também são opcionais: uma falha sobre um documento inteiro carrega apenas file. lockfile é um lockfile. release é a Release de que trata o erro, escrita da forma como a requisição a nomeou, para que um cliente possa compor aggrega pull --release <release> sem precisar extraí-la da mensagem. unreachable diz que o registry que uma requisição recusada nomeou não pôde ser alcançado: uma atualização de índice recusada que nomeia um registry a carrega, lida a partir da própria falha, e um registry que respondeu a deixa ausente. Cada chave é opcional e está presente somente quando o daemon tem esse valor em mãos; nenhuma substitui outra, então aquilo para que uma chave aponta nunca depende do código ao lado.

code e shortCode em data nomeiam a condição que uma recusa relata, em toda recusa que relata uma condição registrada, seja qual for seu código numérico: o código descritivo pelo 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 carrega para a mesma condição, e listados na tabela de todas as condições. Ramifique por code. O código numérico nomeia o estado da requisição e permanece o mesmo para muitas condições — uma build recusada porque um link do catálogo leva para fora e uma build recusada porque um nome não se resolve em nada são ambas 1004 — e a mensagem é prosa que pode ser reformulada, então nenhum dos dois distingue uma condição de outra. Invalid-params é um desses códigos compartilhados: uma requisição que nomeia um workspace cujo arquivo de configuração leva para fora dele também o provoca, e ali read-leads-out-of-workspace diz que a falha está na estrutura do workspace, que uma pessoa repara, e não na requisição. Uma recusa que não relata nenhuma condição registrada não carrega nenhuma das duas chaves, e as duas estão presentes juntas ou não estão. A mensagem de uma recusa que nomeia uma condição começa com seu código curto, E0321: …, uma única vez, que é a forma que uma pessoa encontra ao lê-la em toda recusa desse tipo; uma recusa cuja mensagem já começa com um cabeçalho entre colchetes que carrega o código — o relatório de uma linha sobre um documento do catálogo que o carregamento recusou — não o recebe de novo.

O relato de como a cascata de Release do workspace foi executada viaja na resposta de aggrega/activeRelease, em seu campo trace, e não em um erro: um workspace que não aponta para nenhuma Release é um estado comum, e não uma requisição com falha. É prosa de diagnóstico escrita para uma pessoa ler, não uma estrutura para analisar. Mostre-a como está — grave-a em um log ou em um painel que o usuário possa abrir — e não compare padrões com ela, não extraia valores dela nem ramifique pelos rótulos que ela usa: sua redação, seu layout e esses rótulos acompanham a própria cascata e mudam sempre que a cascata muda. Um cliente que repassa o texto continua funcionando após essa mudança; um que aprendeu sua forma quebra com ela.

Veja também

  • ../schema/other/serve-wire.md — as formas das mensagens que este protocolo troca, geradas a partir do schema publicado: o objeto de parâmetros de cada método, cada resultado e cada payload de notificação, campo por campo.
  • ./aggrega-build.md — o comando build, cujo pipeline do compilador, verificações e resolução de dependências aggrega/build também executa, de modo que as duas superfícies gravam uma única árvore de saída, e não duas.
  • ./aggrega-version.md — o comando version que uma extensão do editor usa para verificar a compatibilidade do daemon.
  • ./aggrega-pull.md — o lockfile que a superfície de drift do daemon lê.
  • ./aggrega-lint.md — as convenções de publicação que o daemon relata sob demanda, e em toda validação depois que serve.lint_on_validate estiver ativado.

Sinopse

aggrega serve [flags]

Descrição

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

Flags

FlagPadrãoDescrição
--build-on-inspectfalseExecuta a etapa de renderização de artefatos ao inspecionar um grafo IR, para que os avisos que aggrega build emite durante a renderização também apareçam como problemas no editor. Não adiciona nenhuma das verificações em que uma build é interrompida. Nada é gravado em disco: nenhum artefato renderizado, nenhum diretório de saída, nenhum lockfile. Desativado por padrão, em linha com aggrega inspect, que também não emite esse tipo de aviso. Quando definido, sobrescreve a chave de configuração serve.build_on_inspect.