Lint e formattazione automatica del codice prima dei commit

[Discourse]

Discourse utilizza lefthook per gli hook di git e bin/lint come punto di ingresso principale della CLI per eseguire manualmente gli stessi controlli.

Se stai lavorando su un clone locale, installa gli hook una sola volta:

pnpm install
pnpm lefthook install

Dopo di che, i file in staging verranno controllati automaticamente al momento di git commit.

Il comando principale: bin/lint

Usa bin/lint quando vuoi eseguire tu stesso i linter configurati nel repository, invece di aspettare l’hook pre-commit.

Esempi comuni:

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

Cosa fa ciascuna modalità

• bin/lint: esegue il lint di tutti i file supportati nel repository
• bin/lint path/to/file ...: esegue il lint solo dei file specificati
• bin/lint --recent: esegue il lint dei file modificati negli ultimi 50 commit, più i file non tracciati
• bin/lint --staged: esegue il lint solo dei file in staging
• bin/lint --unstaged: esegue il lint solo dei file non in staging
• bin/lint --wip: esegue il lint dei file in staging, dei file non in staging e dei file modificati rispetto a main
• bin/lint --fix ...: esegue i correttori automatici per i file selezionati
• bin/lint --fix: esegue tutti i correttori automatici disponibili su tutto il repository
• bin/lint --verbose: stampa i comandi lefthook sottostanti

Quando si passano file espliciti, bin/lint li filtra per i tipi di file lintabili supportati prima di richiamare lefthook.

I file di documentazione Markdown non fanno attualmente parte di bin/lint, quindi l’esecuzione di bin/lint path/to/doc.md segnalherà che non ci sono file corrispondenti da sottoporre a lint.

Cosa viene sottoposto a lint

La configurazione esatta si trova in lefthook.yml. Al momento della stesura, bin/lint copre:

Ruby

• **/*.{rb,rake,thor}
• Script Ruby sotto bin/**/*
• Gemfile

Controlli:

• rubocop
• syntax_tree (stree check)

Formattazione di JavaScript, GJS, CSS e SCSS

• app/assets/stylesheets/**/*.{css,scss}
• frontend/**/*.{js,gjs,scss,css,cjs,mjs}
• File di asset corrispondenti per plugin e temi

Controlli:

• prettier/pprettier

Linting di JavaScript e GJS

• frontend/**/*.{js,gjs}
• File JS corrispondenti per plugin e temi

Controlli:

• eslint (con le regole template-* di eslint-plugin-ember che coprono la parte di template dei file .gjs)

Linting di SCSS

• app/assets/stylesheets/**/*.scss
• File SCSS corrispondenti per plugin e temi

Controlli:

• stylelint

Controlli YAML e di localizzazione

• **/*.{yaml,yml} ad eccezione di config/database.yml
• **/{client,server}.en.yml

Controlli:

• yaml-lint
• script/i18n_lint.rb

Verifica dei tipi

Quando si esegue bin/lint senza argomenti di file, il lint dell’intero repository esegue anche:

• pnpm lint:types

Questo è il controllo di stile Glint/TypeScript per le informazioni sui tipi di JavaScript di Discourse.

bin/lint path/to/file e l’hook pre-commit non eseguono la verifica completa dei tipi. Usa bin/lint semplice quando vuoi un passaggio di lint completo su tutto il repository.

Cosa può essere corretto automaticamente

bin/lint --fix può correggere automaticamente molti problemi, ma non tutti.

La correzione automatica è configurata per:

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

In pratica, questo significa che --fix può riformattare e riscrivere:

• Ruby
• JavaScript / GJS
• CSS / SCSS

Questi controlli non vengono corretti automaticamente da bin/lint --fix:

• Validazione della sintassi YAML
• Linting i18n per client.en.yml / server.en.yml
• Verifica dei tipi Glint

Relazione con gli hook di git

L’hook pre-commit utilizza la stessa configurazione lefthook di bin/lint, ma viene eseguito solo sui file in staging.

Questo significa che:

• un commit può fallire perché i file in staging non superano il lint
• bin/lint --staged è l’equivalente manuale più vicino all’hook pre-commit
• bin/lint --fix --staged è un buon modo per riparare esattamente ciò che stai per commitare

Flusso di lavoro pratico

Per lo sviluppo quotidiano, questi sono i comandi più utili:

# Prima di commitare un paio di file modificati
bin/lint --fix path/to/file1.rb path/to/file2.gjs

# Controlla esattamente cosa verificherà l'hook pre-commit
bin/lint --staged

# Pulisci tutto il lavoro corrente in corso
bin/lint --fix --wip

# Esegui la suite completa di lint del repository, inclusi i controlli dei tipi
bin/lint

---

Questo documento è sottoposto a controllo di versione - suggerisci modifiche su github.