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

[Discourse]

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

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

pnpm install
pnpm lefthook install

Depois disso, os arquivos estagiados serão verificados automaticamente no git commit.

O comando principal: bin/lint

Use bin/lint quando quiser executar os linters configurados do repositório por conta própria, em vez de aguardar o 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: lint todos os arquivos suportados no repositório
• bin/lint path/to/file ...: lint apenas os arquivos fornecidos
• bin/lint --recent: lint arquivos alterados nos últimos 50 commits, além de arquivos não rastreados
• bin/lint --staged: lint apenas arquivos estagiados
• bin/lint --unstaged: lint apenas arquivos não estagiados
• bin/lint --wip: lint arquivos estagiados, arquivos não estagiados e arquivos alterados desde a main
• bin/lint --fix ...: executa os auto-fixers 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ê fornece arquivos explícitos, o bin/lint os filtra para tipos de arquivo lintáveis suportados antes de invocar o lefthook.

Arquivos Markdown são lints apenas sob docs/developer-guides/. Executar bin/lint path/to/doc.md em qualquer outro arquivo Markdown reportará que nada foi lints.

O que é lints

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 correspondentes de plugins e temas

Verificações:

• prettier/pprettier

Linting 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)

Linting de SCSS

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

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

Este é o estilo de verificação Glint/TypeScript para as informações de tipo do Discourse. Ele roda no modo strict do TypeScript e também gera as declarações publicadas.

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

Auto-fix está configurado 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 i18n para client.en.yml / server.en.yml
• Verificação de tipos/Glint

Relação com hooks de git

O hook pre-commit usa a mesma configuração do lefthook que o bin/lint, mas ele executa apenas contra arquivos estagiados.

Isso significa:

• um commit pode falhar porque os arquivos estagiados não passam no linting
• bin/lint --staged é o equivalente manual mais próximo ao 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 diário, 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.