Formattare e fare il lint automatico del codice prima dei commit

[Discourse]

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

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

pnpm install
pnpm lefthook install

Dopo di ciò, i file sottoposti a staging verranno controllati automaticamente al momento di git commit.

Il comando principale: bin/lint

Usa bin/lint quando vuoi eseguire tu stesso gli strumenti di linting configurati nel repository invece di aspettare l’hook di 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 ogni modalità

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

Quando passi file espliciti, bin/lint li filtra per i tipi di file supportati da sottoporre a linting prima di invocare lefthook.

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

Cosa viene sottoposto a linting

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 JavaScript, GJS, CSS e SCSS

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

Controlli:

• prettier/pprettier

Linting JavaScript e GJS

• frontend/**/*.{js,gjs}
• file JS di plugin e temi corrispondenti

Controlli:

• eslint

Linting dei template GJS

• frontend/**/*.gjs
• file .gjs di plugin e temi corrispondenti

Controlli:

• ember-template-lint

Linting SCSS

• app/assets/stylesheets/**/*.scss
• file SCSS di plugin e temi corrispondenti

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

Controllo dei tipi (Type checking)

Quando esegui bin/lint senza argomenti di file, viene eseguito anche il linting dell’intero repository:

• pnpm lint:types

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

bin/lint path/to/file e l’hook di pre-commit non eseguono il controllo completo dei tipi. Usa semplicemente bin/lint quando desideri la suite completa di linting dell’intero repository.

Cosa può essere auto-corretto

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

L’auto-correzione è configurata per:

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

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

• Ruby
• JavaScript / GJS
• CSS / SCSS

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

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

Relazione con gli hook di git

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

Ciò significa che:

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

Flusso di lavoro pratico

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

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

# Controlla esattamente ciò che controllerà l'hook di pre-commit
bin/lint --staged

# Pulisce tutto il lavoro attualmente in corso
bin/lint --fix --wip

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

---

Questo documento è controllato tramite versione - suggerisci modifiche su github.