Linter e formatação automáticos de código antes dos commits

[Discourse]

O Discourse usa o lefthook para git hooks 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 hooks uma vez:

pnpm install
pnpm lefthook install

Depois disso, os arquivos em staging serão verificados automaticamente no 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 hook 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: faz o lint de todos os arquivos suportados no repositório
• bin/lint path/to/file ...: faz o lint apenas dos arquivos fornecidos
• bin/lint --recent: faz o lint dos arquivos alterados nos últimos 50 commits, além dos arquivos não rastreados
• bin/lint --staged: faz o lint apenas dos arquivos em staging
• bin/lint --unstaged: faz o lint apenas dos arquivos fora do staging
• bin/lint --wip: faz o lint dos arquivos em staging, dos arquivos fora do staging e dos arquivos alterados desde o main
• bin/lint --fix ...: executa os corretores automáticos para os arquivos selecionados
• bin/lint --fix: executa todos os corretores automáticos disponíveis em todo o repositório
• bin/lint --verbose: imprime os comandos subjacentes do lefthook

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

Os arquivos de documentação em Markdown não fazem parte do bin/lint no momento, portanto, executar bin/lint path/to/doc.md reportará que não há arquivos correspondentes para lint.

O que é verificado

A configuração exata está em lefthook.yml. No momento da escrita, o 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

Linting de JavaScript e GJS

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

Verificações:

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

Linting de SCSS

• 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 completo do repositório também executa:

• pnpm lint:types

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

bin/lint path/to/file e o hook pre-commit não executam a verificação completa de tipos. Use o bin/lint simples quando quiser 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 nem todos.

A correção automática 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

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

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

Relação com os git hooks

O hook pre-commit usa a mesma configuração do lefthook que o bin/lint, mas ele é executado apenas contra os arquivos em staging.

Isso significa que:

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

Fluxo de trabalho prático

Para o desenvolvimento do dia a dia, estes são os comandos mais úteis:

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

# Verificar exatamente o que o hook pre-commit verificará
bin/lint --staged

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

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

---

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