Lint y formateo automático de código antes de los commits

[Discourse]

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

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

pnpm install
pnpm lefthook install

A partir de ese momento, los archivos en el área de preparación (staged) se verificarán automáticamente al ejecutar git commit.

El comando principal: bin/lint

Usa bin/lint cuando quieras ejecutar los linters configurados en el repositorio tú mismo en lugar de esperar al hook 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: verifica todos los archivos soportados en el repositorio
• bin/lint path/to/file ...: verifica solo los archivos indicados
• bin/lint --recent: verifica los archivos modificados en los últimos 50 commits, más los archivos no rastreados
• bin/lint --staged: verifica solo los archivos en el área de preparación (staged)
• bin/lint --unstaged: verifica solo los archivos fuera del área de preparación (unstaged)
• bin/lint --wip: verifica los archivos en staging, los archivos fuera de staging y los archivos modificados desde main
• bin/lint --fix ...: ejecuta los auto-correcciones para los archivos seleccionados
• bin/lint --fix: ejecuta todas las auto-correcciones 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 soportados para linting antes de invocar 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 verificar.

Qué se verifica con lint

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

Ruby

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

Verificaciones:

• 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 coincidentes de plugins y temas

Verificaciones:

• prettier/pprettier

Verificación (linting) de JavaScript y GJS

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

Verificaciones:

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

Verificación (linting) de SCSS

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

Verificaciones:

• stylelint

Verificaciones de YAML y locales

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

Verificaciones:

• yaml-lint
• script/i18n_lint.rb

Verificación de tipos

Cuando ejecutas bin/lint sin argumentos de archivo, también se ejecuta la verificación completa del repositorio:

• pnpm lint:types

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

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

Qué puede ser auto-corregido

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

La auto-corrección 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 verificaciones no son auto-corregidas por bin/lint --fix:

• Validación de sintaxis YAML
• Verificación i18n para client.en.yml / server.en.yml
• Verificación Glint/de tipos

Relación con los hooks de git

El hook pre-commit utiliza la misma configuración de lefthook que bin/lint, pero solo se ejecuta sobre archivos en el área de preparación (staged).

Esto significa que:

• un commit puede fallar porque los archivos en staging no pasan la verificación
• bin/lint --staged es la equivalente manual más cercana al hook 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

# Verificar exactamente lo que verificará el hook pre-commit
bin/lint --staged

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

# Ejecutar la suite completa de linting del repositorio, incluyendo verificaciones de tipos
bin/lint

---

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