Exporte uma fatia determinística de um workspace com perspectivas

Também em: English, Español, 日本語, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · Todos os guias em português

Aviso: desenvolvemos o Carbon Forge na 100monkeys.ai, então leia isto como o relato de quem o fabrica. Este guia foi redigido por um dos nossos agentes de IA a partir da documentação pública, principalmente Perspectives: beam angles through one workspace e a seção Perspectives de Source control settings, e revisado pela empresa; esta versão em português é uma tradução do guia original em inglês. A perspectiva e as chamadas são os exemplos da própria documentação, e as citações ficam em inglês com a tradução ao lado. Onde a documentação deixa uma pergunta em aberto, a última seção diz isso.

O que é uma perspectiva

A documentação: "A perspective is a named lens through that record. It picks out a part of it, by kind, surface, path, media type, tag or metadata, and answers that part at paths of its own." (Uma perspectiva é uma lente com nome através desse registro. Ela escolhe uma parte, por tipo, superfície, caminho, tipo de mídia, tag ou metadados, e responde essa parte em caminhos próprios.) E: "Nothing is copied to make one." (Nada é copiado para criar uma.) Duas propriedades importam para uma exportação. Ela é somente leitura pelo alcance: "A perspective never discloses. It narrows what the reader already reads and never widens it." (Uma perspectiva nunca revela. Ela estreita o que o leitor já lê e nunca o amplia.) E o download é determinístico: "The same ref through the same perspective gives the same bytes." (A mesma ref pela mesma perspectiva dá os mesmos bytes.)

Passo 1. Liste as perspectivas que o workspace resolve

Chame perspectives.list. Todo workspace tem perspectivas embutidas: all, code, docs, adrs, internal, public (exatamente o que é servido a um leitor anônimo) e uma tree:<path> por árvore de código, com raiz nessa árvore. Um administrador da instância pode adicionar perspectivas para a instância toda, e as do próprio workspace vêm por último; "The nearest layer wins" (vence a camada mais próxima). Cada resposta nomeia a sua source e as fontes que ela overrides. Se uma embutida já serve, pule para o passo 3.

Passo 2. Escreva a sua na página .perspectives

As perspectivas do workspace ficam na página reservada .perspectives, como um bloco JSON delimitado ou uma tabela. O exemplo da documentação, reduzido a uma perspectiva:

{
  "perspectives": [
    {
      "name": "api",
      "title": "API service",
      "description": "The api tree's source and README, without generated files.",
      "include": [
        { "kinds": ["tree"], "paths": ["/services/api/src", "/services/api/README*"] }
      ],
      "exclude": [{ "paths": ["*.generated.ts"] }],
      "root": "services/api"
    }
  ]
}

Uma regra casa quando todos os campos que ela nomeia casam; include pega tudo o que alguma regra casa, e exclude tira tudo o que alguma regra casa, "even when an include rule matched it" (mesmo quando uma regra include o pegou). Os caminhos são globs no estilo gitignore e não podem começar com !. Com root definido, a raiz é retirada de cada caminho, então esta perspectiva responde src/main.ts e README.md. Árvores de código são avaliadas arquivo por arquivo. Templates como monorepo, service, library ou docs-site podem escrever a página para você com perspectives.adopt, ou com Adopt em Settings, Workspace, Source control.

Uma linha ruim não é pulada. "When the page cannot be read, every perspective read in the workspace is refused, quoting the page's first bad row, until it is fixed." (Quando a página não pode ser lida, toda leitura por perspectiva no workspace é recusada, citando a primeira linha ruim da página, até ela ser corrigida.) A página mostra um painel, Perspectives on this page, que confere de novo a cada gravação.

Passo 3. Faça a prévia numa ref

perspectives.preview conta o que a perspectiva contém numa ref, por tipo, e responde os primeiros caminhos projetados, 100 por padrão e no máximo 500. "It stores nothing, so it is the way to check a perspective before downloading it." (Não guarda nada, então é o jeito de conferir uma perspectiva antes de baixá-la.) No navegador, a mesma contagem aparece ao lado do seletor na barra de refs do navegador de código: Selects <n> pages, <n> atoms, <n> code trees, <n> files, <n> library entries at <ref>.

Passo 4. Escolha uma ref que não se mova

Uma ref é trunk (o padrão), lane:<label>, cut:<name> ou snapshot:<id>. O job de exportação resolve a ref quando roda, "so trunk is the trunk at that moment. Name a cut or a snapshot for a point that does not move." (então trunk é o trunk naquele momento. Nomeie um corte ou um snapshot para um ponto que não se mova.) Para um download que você queira reproduzir, nomeie um corte. Uma lane em conflito é recusada até o conflito ser resolvido.

Passo 5. Exporte e baixe o arquivo

perspectives.export { "perspective": "api", "ref": "cut:<name>", "format": "tar" }
→ { export_id, status: "queued" }
exports.status { ... }   // until it answers a download_url

Consulte exports.status com o id da exportação até ele responder uma download_url; quem pediu também recebe um e-mail com um link. O arquivo se chama <workspace>-<perspective>-<ref>.zip ou .tar. Dentro, uma página ou um átomo é um arquivo Markdown com frontmatter para título, tipo e metadados; um arquivo de código mantém seus bytes e seu modo; um link simbólico continua link simbólico. As entradas são ordenadas pelos bytes do caminho, cada arquivo leva a hora da ref, nada é comprimido e nenhum dono é gravado. Um zip comporta no máximo 65.535 entradas e 4 GiB; acima disso, use tar. No navegador, escolha zip ou tar e clique em Download ao lado da prévia.

Passo 6. Confira cada arquivo com o manifesto

Todo arquivo exportado leva .carbon/perspective.json, no formato carbon-perspective/1. Ele nomeia a instância, o workspace, a perspectiva como foi resolvida e a ref: um corte ou snapshot pelo id do snapshot, o trunk ou uma lane por composition_sha256. Cada entrada lista:

path, kind, entity_id, revision_id, content_hash, seal_hash, mode, size, sha256

Calcule o hash de cada arquivo e compare com sha256; compare revision_id, content_hash e seal_hash com o registro. A documentação: com o manifesto, "a reader can check every file against the record it came from" (um leitor pode conferir cada arquivo com o registro de onde veio). É isso que faz do arquivo uma fatia do registro e não "a copy that can drift into a second truth." (uma cópia que pode derivar até virar uma segunda verdade).

Passo 7. Traga as mudanças de volta por uma lane

"A download is read-only by design. Nothing in the archive is read back." (Um download é somente leitura por design. Nada do arquivo é lido de volta.) Para devolver o trabalho feito sobre o arquivo, grave-o com uma chamada de ferramenta, coloque-o numa lane e integre, ou importe-o, para que cada mudança leve seu próprio ator e intenção. Working in lanes explica a lane, e o nosso guia Corte uma versão no Carbon Forge e envie-a ao GitHub explica como fazer o corte de onde você exporta.

O que a documentação deixa sem resposta

• O tamanho do limite de exportação. Um download acima dele falha com uma frase que nomeia o limite, mas a documentação não diz o valor padrão.
• Por quanto tempo uma download_url continua válida, e por quanto tempo uma exportação é guardada.
• Quem pode editar .perspectives. Adotar um template é uma ação de administrador; a página em si "is edited like any other page" (é editada como qualquer outra página), o que se lê como qualquer editor.
• Uma ferramenta para conferir um arquivo com o seu manifesto. O formato está descrito; a conferência fica a cargo do script de cada leitor.