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

[Discourse]

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

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

pnpm install
pnpm lefthook install

Después de eso, los archivos en staging se comprobarán automáticamente al ejecutar 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 hook 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

Qué hace cada modo

• bin/lint: analiza todos los archivos compatibles del repositorio
• bin/lint path/to/file ...: analiza solo los archivos indicados
• 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 en staging
• bin/lint --unstaged: analiza solo los archivos sin staging
• bin/lint --wip: analiza archivos en staging, archivos sin staging y archivos modificados desde main
• bin/lint --fix ...: ejecuta los correctores automáticos para los archivos seleccionados
• bin/lint --fix: ejecuta todos los correctores automáticos disponibles en todo el repositorio
• bin/lint --verbose: imprime los comandos subyacentes de lefthook

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

Los archivos de documentación en 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 la redacción, bin/lint cubre:

Ruby

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

Comprobaciones:

• rubocop
• syntax_tree (stree check)

Formateo de JavaScript, GJS, CSS y SCSS

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

Comprobaciones:

• prettier/pprettier

Análisis de JavaScript y GJS

• frontend/**/*.{js,gjs}
• Archivos JS de plugins y temas coincidentes

Comprobaciones:

• eslint (con las reglas template-* de eslint-plugin-ember que cubren la parte de plantilla de los archivos .gjs)

Análisis de SCSS

• app/assets/stylesheets/**/*.scss
• Archivos SCSS de plugins 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 ejecuta:

• pnpm lint:types

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

bin/lint path/to/file y el hook de pre-commit no ejecutan la comprobación completa de tipos. Usa bin/lint simple cuando quieras una pasada completa de análisis en todo el repositorio.

Qué puede corregirse 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
• 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 Glint/tipos

Relación con los hooks de git

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

Eso significa que:

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

Flujo de trabajo práctico

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

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

# Comprobar exactamente lo que el hook de pre-commit va a comprobar
bin/lint --staged

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

# Ejecutar la suite completa de análisis del repositorio, incluidas las comprobaciones de tipos
bin/lint

---

Este documento está bajo control de versiones - sugiere cambios en github.