Lintar e formatar código automaticamente antes dos commits

[Discourse]

O Discourse utiliza o lefthook para hooks do git e o bin/lint como o principal ponto de entrada da CLI para executar as mesmas verificações manualmente.

Se você estiver trabalhando em um clone local, instale os hooks uma única vez:

pnpm install
pnpm lefthook install

Após isso, os arquivos em estágio serão verificados automaticamente ao executar git commit.

O comando principal: bin/lint

Use bin/lint quando quiser executar os linters configurados no repositório manualmente, em vez de aguardar o hook de pré-commit.

Exemplos comuns:

bin/lint
bin/lint path/to/file.rb path/to/file.gjs
bin/lint --recent
bin/lint --staged
bin/lint --unstaged
bin/lint --wip
bin/lint --fix path/to/file.rb
bin/lint --fix --recent
bin/lint --fix

O que cada modo faz

• bin/lint: verifica todos os arquivos suportados no repositório
• bin/lint path/to/file ...: verifica apenas os arquivos especificados
• bin/lint --recent: verifica arquivos alterados nos últimos 50 commits, além de arquivos não rastreados
• bin/lint --staged: verifica apenas arquivos em estágio
• bin/lint --unstaged: verifica apenas arquivos fora do estágio
• bin/lint --wip: verifica arquivos em estágio, arquivos fora do estágio e arquivos alterados desde main
• bin/lint --fix ...: executa os auto-corretores para os arquivos selecionados
• bin/lint --fix: executa todos os auto-corretores disponíveis em todo o repositório
• bin/lint --verbose: imprime os comandos subjacentes do lefthook

Ao passar arquivos explícitos, o bin/lint filtra-os para tipos de arquivo verificáveis suportados antes de invocar o lefthook.

Arquivos de documentação Markdown não fazem parte atualmente do bin/lint, portanto, executar bin/lint path/to/doc.md informará que não há arquivos correspondentes para verificar.

O que é verificado

A configuração exata está em lefthook.yml. No momento da escrita, o bin/lint abrange:

Ruby

• **/*.{rb,rake,thor}
• Scripts Ruby em bin/**/*
• Gemfile

Verificações:

• rubocop
• syntax_tree (stree check)

Formatação de JavaScript, GJS, CSS e SCSS

• app/assets/stylesheets/**/*.{css,scss}
• frontend/**/*.{js,gjs,scss,css,cjs,mjs}
• Arquivos de ativos correspondentes de plugins e temas

Verificações:

• prettier/pprettier

Verificação de JavaScript e GJS

• frontend/**/*.{js,gjs}
• Arquivos JS correspondentes de plugins e temas

Verificações:

• eslint (com as regras template-* do eslint-plugin-ember cobrindo a parte de template dos arquivos .gjs)

Verificação de SCSS

• app/assets/stylesheets/**/*.scss
• Arquivos SCSS correspondentes de plugins e temas

Verificações:

• stylelint

Verificações de YAML e localidade

• **/*.{yaml,yml} exceto config/database.yml
• **/{client,server}.en.yml

Verificações:

• yaml-lint
• script/i18n_lint.rb

Verificação de tipos

Ao executar bin/lint sem argumentos de arquivo, a verificação completa do repositório também é executada:

• pnpm lint:types

Esta é a verificação no estilo Glint/TypeScript para informações de tipo do JavaScript do Discourse.

bin/lint path/to/file e o hook de pré-commit não executam a verificação completa de tipos. Use bin/lint simples quando quiser a passagem completa de verificação em todo o repositório.

O que pode ser auto-corrigido

O bin/lint --fix pode corrigir automaticamente muitos problemas, mas não todos.

A auto-correção está configurada para:

• prettier --write
• eslint --fix
• stylelint --fix
• rubocop -A
• syntax_tree (stree write)

Na prática, isso significa que --fix pode reformatar e reescrever:

• Ruby
• JavaScript / GJS
• CSS / SCSS

Essas verificações não são auto-corrigidas pelo bin/lint --fix:

• Validação de sintaxe YAML
• Verificação i18n para client.en.yml / server.en.yml
• Verificação Glint/Tipos

Relação com hooks do git

O hook de pré-commit usa a mesma configuração do lefthook que o bin/lint, mas executa apenas em relação aos arquivos em estágio.

Isso significa que:

• um commit pode falhar porque arquivos em estágio não passam na verificação
• bin/lint --staged é o equivalente manual mais próximo do hook de pré-commit
• bin/lint --fix --staged é uma boa maneira de reparar exatamente o que você está prestes a confirmar

Fluxo de trabalho prático

Para o desenvolvimento diário, estes são os comandos mais úteis:

# Antes de confirmar alguns arquivos alterados
bin/lint --fix path/to/file1.rb path/to/file2.gjs

# Verifique exatamente o que o hook de pré-commit verificará
bin/lint --staged

# Limpe todo o trabalho atual em andamento
bin/lint --fix --wip

# Execute a suíte completa de verificação do repositório, incluindo verificações de tipo
bin/lint

---

Este documento está sob controle de versão - sugira alterações no GitHub.