Lint e formate automaticamente o código antes dos commits

[Discourse]

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

Se você estiver trabalhando em um clone local, instale os ganchos uma vez:

pnpm install
pnpm lefthook install

Depois disso, os arquivos staged (preparados) serão verificados automaticamente em git commit.

O comando principal: bin/lint

Use bin/lint quando quiser executar os linters configurados do repositório você mesmo, em vez de esperar pelo gancho pre-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: executa o lint em todos os arquivos suportados no repositório
• bin/lint path/to/file ...: executa o lint apenas nos arquivos fornecidos
• bin/lint --recent: executa o lint em arquivos alterados nos últimos 50 commits, mais arquivos não rastreados
• bin/lint --staged: executa o lint apenas em arquivos staged
• bin/lint --unstaged: executa o lint apenas em arquivos unstaged
• bin/lint --wip: executa o lint em arquivos staged, unstaged e arquivos alterados desde main
• bin/lint --fix ...: executa os auto-fixers (corretores automáticos) para os arquivos selecionados
• bin/lint --fix: executa todos os auto-fixers disponíveis em todo o repositório
• bin/lint --verbose: imprime os comandos subjacentes do lefthook

Quando você passa arquivos explícitos, bin/lint os filtra para tipos de arquivo suportados para lintagem antes de invocar o lefthook.

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

O que é inspecionado (linted)

A configuração exata reside em lefthook.yml. No momento da escrita, bin/lint cobre:

Ruby

• **/*.{rb,rake,thor}
• Scripts Ruby sob 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 assets de plugins e temas correspondentes

Verificações:

• prettier/pprettier

Inspeção de JavaScript e GJS (Linting)

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

Verificações:

• eslint

Inspeção de templates GJS (Linting)

• frontend/**/*.gjs
• arquivos .gjs de plugins e temas correspondentes

Verificações:

• ember-template-lint

Inspeção de SCSS (Linting)

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

Verificações:

• stylelint

Verificações de YAML e localização

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

Verificações:

• yaml-lint
• script/i18n_lint.rb

Verificação de tipos

Quando você executa bin/lint sem argumentos de arquivo, o lint de todo o repositório também é executado:

• pnpm lint:types

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

bin/lint path/to/file e o gancho pre-commit não executam a verificação completa de tipos. Use apenas bin/lint quando desejar a passagem completa de lint em todo o repositório.

O que pode ser corrigido automaticamente

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

A correção automática está configurada para:

• prettier --write
• eslint --fix
• ember-template-lint --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

Estas verificações não são corrigidas automaticamente por bin/lint --fix:

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

Relação com ganchos git

O gancho pre-commit usa a mesma configuração do lefthook que o bin/lint, mas é executado apenas contra arquivos staged.

Isso significa que:

• um commit pode falhar porque os arquivos staged não passam na inspeção (lintagem)
• bin/lint --staged é o equivalente manual mais próximo do gancho pre-commit
• bin/lint --fix --staged é uma boa maneira de reparar exatamente o que você está prestes a confirmar (commit)

Fluxo de trabalho prático

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

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

# Verifica exatamente o que o gancho pre-commit verificará
bin/lint --staged

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

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

---

Este documento é controlado por versão - sugira alterações no github.