Contributing pt

Contribuindo

English | 中文 | 日本語 | 한국어 | Español | Português | Русский

Comandos

npm test                        # full test suite (Node built-in runner, no build needed)
node --test test/foo.test.mjs   # single file
npm run package                 # build the versioned zip (browsa-vX.Y.Z.zip)
npm run build                   # esbuild vendor bundle (only needed after build.mjs changes)
bash check-compat.sh            # static compatibility check

A restrição da máquina de 4GB: a suíte tem 103 arquivos (~36 pesados em jsdom) em um VPS de 2CPU/4GB; o script limita a concorrência a 2, prefira --test-concurrency=1 em 4GB. Nunca aloque blobs de dezenas de MB em testes (um único mock de 44MB já derrubou a máquina por OOM — recorrência real); prefira testes de funções puras (sem DOM, sem buffers grandes).

Filosofia de testes

• Os testes mockam o global chrome antes de importar módulos reais; testes jsdom usam os bundles REAIS vendored de marked/DOMPurify/katex/highlight.js, não substitutos.
• sidepanel.js tem zero exports — seus testes carregam todo o sidepanel.html no jsdom e o dirigem como caixa-preta (cliques/teclas/mensagens de porta simulados).
• Clients de worker guardam singletons em nível de módulo → cenários que precisam de um singleton fresco DEVEM ser arquivos de teste separados (o runner isola por arquivo/processo).
• Disciplina de lockstep: fatos espelhados em vários lugares (regexes, nomes de campos, pares CSS/hint, ordem de abas) ou colapsam em uma fonte única ou são fixados por source-regex com uma nota no AGENTS.md de "mude ambos em lockstep". Exemplo: subchat.test.mjs fixa por regex a linha exata do código pushSubChatChunk(… SUBCHAT_DONE …).
• Testes de thread de detalhe / streaming DEVEM encerrar o turno (DONE / ■ / fechar), ou o intervalo SW_PING de 20s da porta do turno vaza e trava o runner.
• WASM é a exceção à regra "sem execução real": WebAssembly.instantiate roda em Node, então os testes do pdf-inspector executam o binário vendored real.

Princípios de refatoração (ganhos através de incidentes; do AGENTS.md)

• N cases de switch que diferem só por literais → uma tabela de consulta; duas implementações escritas à mão do mesmo protocolo de rede → uma função compartilhada com hooks (o drift do DONE-handler foi uma família real de bugs).
• Após cada extração, rode a suíte COMPLETA E check-compat.sh — uma checagem de sintaxe não prova nada.
• Grep em todo o repositório (incluindo test/) antes de declarar um export morto; um export usado só por teste não está automaticamente morto — leia os comentários ao redor.

dev-preview (prévia da UI da extensão em ambiente headless)

node dev-preview/gen.mjs        # regenerate preview pages from real sidepanel.html (rerun after HTML changes)
python3 -m http.server 8931     # from the repo root
# http://127.0.0.1:8931/dev-preview/sidepanel.preview.html

Um chrome-shim fornece a superfície mínima do chrome.*; o seed.js injeta um histórico rico. Screenshots passam pelo CDP Page.captureScreenshot (simples, sem clip/scale; page.screenshot() tem artefatos de modo escuro). Uma prévia passando ≠ uma extensão real passando: os envelopes sendMessage do shim devem espelhar o contrato real byte a byte, e verificação de classe CSP sempre exige um carregamento real da extensão.

Fluxo de release

1. Suba a versão em manifest.json E package.json.
2. PR → CI verde → squash-merge para a main → back-fill da dev: git reset --hard origin/main && git push --force-with-lease origin dev (back-fill via merge polui main..dev; o botão Delete branch da página do PR apagaria a dev).
3. PRs de bump de versão passam pelos workflows de release reutilizáveis (xiaohuzai/release-flow@v1) com testes dispensados (modo PAT).
4. O texto da listagem da loja é gerado com a skill .agents/skills/cws-listing (a tag é a fonte da verdade da versão); o histórico de rejeições está registrado.
5. Disciplina de docs-sync (qualquer mudança visível ao usuário, mesmo PR): README nos dois idiomas (espelhos alinhados por seção) → o site de docs (dois idiomas) → screenshots/banners/GIF de demo/vídeo promocional cada um CONSIDERADO (legibilidade julgada na resolução do próprio asset; um GIF alterado deve mudar de nome de arquivo para vencer caches) → fatos de nível de arquitetura registrados no AGENTS.md.

Linhas vermelhas (lista rápida)

Sem auto-commit/empacotamento (espere instrução explícita) · sem rodada completa de testes antes do empacotamento (verde direcionado basta) · use a versão atual, nunca suba a versão por conta própria · a chave privada da extensão nunca sai de /root/workspace/browsa-keys/ · texto voltado ao usuário evita jargão (o zh não carrega jargão em inglês) · pixels de imagens armazenados nunca são destruídos · thinking tem padrão omit.

---

Versões autoritativas: Contributing (inglês) / Contributing-zh (chinês) — instantâneo de primeira tradução por IA, sincronizado em 2026-10-01.