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 le stesse verifiche.

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

pnpm install
pnpm lefthook install

Dopo questo passaggio, i file in staging verranno controllati automaticamente durante git commit.

Il comando principale: bin/lint

Usa bin/lint quando desideri 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 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, oltre ai file non tracciati
• bin/lint --staged: esegue il linting solo dei file in staging
• bin/lint --unstaged: esegue il linting solo dei file non in staging
• bin/lint --wip: esegue il linting 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 in base ai tipi di file lintabili supportati prima di invocare lefthook.

I file Markdown vengono sottoposti a linting solo sotto docs/developer-guides/. L’esecuzione di bin/lint path/to/doc.md su qualsiasi altro file Markdown segnalerà che nessun file è stato sottoposto 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

Verifiche:

• 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 di plugin e temi

Verifiche:

• prettier/pprettier

Linting di JavaScript e GJS

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

Verifiche:

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

Linting di SCSS

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

Verifiche:

• stylelint

Verifiche YAML e localizzazione

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

Verifiche:

• yaml-lint
• script/i18n_lint.rb

Controllo dei tipi

Quando si esegue bin/lint senza argomenti di file, il linting completo del repository esegue anche:

• pnpm lint:types

Questo è il controllo in stile Glint/TypeScript per le informazioni sui tipi di Discourse. Viene eseguito in modalità strict di TypeScript e genera anche le dichiarazioni pubblicate.

bin/lint path/to/file e l’hook pre-commit non eseguono il controllo completo dei tipi. Usa semplicemente bin/lint quando desideri un passaggio di linting completo su tutto il repository.

Cosa può essere corretto automaticamente

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

Il correttore automatico è configurato 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

Queste verifiche non vengono corrette automaticamente da bin/lint --fix:

• Validazione della sintassi YAML
• Linting della localizzazione per client.en.yml / server.en.yml
• Controllo 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.

Ciò significa che:

• un commit può fallire perché i file in staging non superano il linting
• 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 committare

Flusso di lavoro pratico

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

# Prima di committare alcuni 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 attualmente in corso
bin/lint --fix --wip

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

---

Questo documento è versionato - suggerisci modifiche su github.