Linter y formatear el 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 manualmente las mismas comprobaciones.

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

pnpm install
pnpm lefthook install

Después de eso, los archivos en el área de preparación (staged) se comprobarán automáticamente al ejecutar git commit.

El comando principal: bin/lint

Usa bin/lint cuando quieras ejecutar tú mismo los linters configurados en el repositorio 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 el área de preparación (staged)
• bin/lint --unstaged: analiza solo los archivos sin preparar (unstaged)
• bin/lint --wip: analiza los archivos en el área de preparación, los archivos sin preparar y los 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 tipos de archivo analizables compatibles antes de invocar lefthook.

Los archivos Markdown solo se analizan bajo docs/developer-guides/. Ejecutar bin/lint path/to/doc.md en cualquier otro archivo Markdown informará que no se analizó nada.

Qué se analiza

La configuración exacta está en lefthook.yml. En el momento de escribir esto, 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 assets 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 cubriendo 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 e idioma

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

Comprobaciones:

• yaml-lint
• script/i18n_lint.rb

Verificació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 Discourse. Se ejecuta en el modo strict de TypeScript y también genera las declaraciones publicadas.

bin/lint path/to/file y el hook de pre-commit no ejecutan la verificación completa de tipos. Usa bin/lint simple cuando quieras pasar completo el análisis de 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
• Verificación de tipos/Glint

Relación con los hooks de git

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

Esto significa que:

• un commit puede fallar porque los archivos en el área de preparación 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 unos pocos archivos modificados
bin/lint --fix path/to/file1.rb path/to/file2.gjs

# Comprobar exactamente qué revisará el hook de pre-commit
bin/lint --staged

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

# Ejecutar la suite completa de análisis del repositorio, incluyendo verificaciones de tipos
bin/lint

---

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