Lintear y formatear código automáticamente antes de los commits

[Discourse]

Discourse utiliza lefthook para los ganchos de git, y bin/lint como el punto de entrada principal de la CLI para ejecutar las mismas comprobaciones manualmente.

Si estás trabajando en un clon local, instala los ganchos una vez:

pnpm install
pnpm lefthook install

Después de eso, los archivos preparados se verificarán automáticamente en git commit.

El comando principal: bin/lint

Usa bin/lint cuando quieras ejecutar los linters configurados del repositorio tú mismo en lugar de esperar al gancho de pre-commit.

Ejemplos comunes:

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

Lo que hace cada modo

• bin/lint: analiza todos los archivos compatibles en el repositorio
• bin/lint path/to/file ...: analiza solo los archivos dados
• bin/lint --recent: analiza los archivos modificados en los últimos 50 commits, más los archivos no rastreados
• bin/lint --staged: analiza solo los archivos preparados
• bin/lint --unstaged: analiza solo los archivos no preparados
• bin/lint --wip: analiza archivos preparados, archivos no preparados y archivos modificados desde main
• bin/lint --fix ...: ejecuta los auto-correctores para los archivos seleccionados
• bin/lint --fix: ejecuta todos los auto-correctores disponibles en todo el repositorio
• bin/lint --verbose: imprime los comandos subyacentes de lefthook

Cuando pasas archivos explícitos, bin/lint los filtra a tipos de archivo compatibles con linting antes de invocar a lefthook.

Los archivos de documentación Markdown no forman parte actualmente de bin/lint, por lo que ejecutar bin/lint path/to/doc.md informará que no hay archivos coincidentes para analizar.

Qué se analiza

La configuración exacta se encuentra en lefthook.yml. En el momento de escribir esto, bin/lint cubre:

Ruby

• **/*.{rb,rake,thor}
• Scripts Ruby bajo bin/**/*
• Gemfile

Comprobaciones:

• rubocop
• syntax_tree (stree check)

Formato de JavaScript, GJS, CSS y SCSS

• app/assets/stylesheets/**/*.{css,scss}
• frontend/**/*.{js,gjs,scss,css,cjs,mjs}
• archivos de activos de complementos y temas coincidentes

Comprobaciones:

• prettier/pprettier

Análisis de JavaScript y GJS

• frontend/**/*.{js,gjs}
• archivos JS de complementos y temas coincidentes

Comprobaciones:

• eslint

Análisis de plantillas GJS

• frontend/**/*.gjs
• archivos .gjs de complementos y temas coincidentes

Comprobaciones:

• ember-template-lint

Análisis de SCSS

• app/assets/stylesheets/**/*.scss
• archivos SCSS de complementos y temas coincidentes

Comprobaciones:

• stylelint

Comprobaciones de YAML y localización

• **/*.{yaml,yml} excepto config/database.yml
• **/{client,server}.en.yml

Comprobaciones:

• yaml-lint
• script/i18n_lint.rb

Comprobación de tipos

Cuando ejecutas bin/lint sin argumentos de archivo, el análisis de todo el repositorio también se ejecuta:

• pnpm lint:types

Esta es la comprobación estilo Glint/TypeScript para la información de tipos de JavaScript de Discourse.

bin/lint path/to/file y el gancho de pre-commit no ejecutan la comprobación de tipos completa. Usa bin/lint simple cuando desees el pase de análisis completo de todo el repositorio.

Qué se puede corregir automáticamente

bin/lint --fix puede corregir automáticamente muchos problemas, pero no todos.

La corrección automática está configurada para:

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

En la práctica, esto significa que --fix puede reformatear y reescribir:

• Ruby
• JavaScript / GJS
• CSS / SCSS

Estas comprobaciones no se corrigen automáticamente con bin/lint --fix:

• Validación de sintaxis YAML
• Análisis de i18n para client.en.yml / server.en.yml
• Comprobación de tipos/Glint

Relación con los ganchos de git

El gancho de pre-commit utiliza la misma configuración de lefthook que bin/lint, pero se ejecuta solo contra los archivos preparados.

Eso significa que:

• un commit puede fallar porque los archivos preparados no pasan el análisis
• bin/lint --staged es el equivalente manual más cercano al gancho de pre-commit
• bin/lint --fix --staged es una buena manera de reparar exactamente lo que estás a punto de confirmar

Flujo de trabajo práctico

Para el desarrollo diario, estos son los comandos más útiles:

# Antes de confirmar un par de archivos modificados
bin/lint --fix path/to/file1.rb path/to/file2.gjs

# Comprueba exactamente lo que comprobará el gancho de pre-commit
bin/lint --staged

# Limpia todo el trabajo actual en curso
bin/lint --fix --wip

# Ejecuta el conjunto de análisis completo del repositorio, incluidas las comprobaciones de tipos
bin/lint

---

Este documento está controlado por versiones: sugiere cambios en github.