El hook pre-commit de 08-04 invocaba shellcheck -x sin explicar qué era. Esta lección lo explica. ShellCheck es un programa que lee tus scripts sin ejecutarlos y te dice dónde están los errores: la variable sin comillas de 03-06, el cd sin || de 05-01, el $? mal usado de 03-04, el local x=$(cmd) que se traga el código de salida de 04-02. Es decir, casi todo lo que este curso te ha enseñado a evitar, más un centenar de casos que no hemos visto. Y junto a él, shfmt, el formateador que cierra lo que 08-01 dejó pendiente: que el estilo deje de ser una discusión de equipo y pase a ser una orden.

1. Qué es el análisis estático y por qué en Bash es imprescindible
2. Instalar y ejecutar ShellCheck
3. Opciones que cambian el resultado
4. Anatomía de un aviso
5. Los avisos que más vas a ver
6. Tabla resumen de códigos
7. Silenciar con criterio
8. shfmt: el formato deja de opinarse
9. Integración: editor, hook y CI
10. Otras herramientas
11. Aplicación: pasar ShellCheck a todo el toolkit

Análisis estático es examinar el código sin ejecutarlo, buscando patrones que casi siempre indican un fallo. Existe para todos los lenguajes, pero en Bash es especialmente valioso por una razón concreta: el intérprete no avisa de casi nada hasta que es demasiado tarde.

Bash ejecuta eso sin una sola queja. No hay compilador, ni comprobación de tipos, ni aviso: simplemente borra en dos rutas distintas, ninguna de las cuales es la que querías. Y lo peor es que funciona perfectamente durante meses mientras ningún directorio tenga espacios. Los bugs de Bash no fallan pronto, esperan.

También hay imagen de contenedor (koalaman/shellcheck) y binario estático, útiles cuando no puedes instalar paquetes en el servidor. Lo que lo hace automatizable es su código de salida: 0 si no hay avisos, 1 si los hay. Por eso el pre-commit de 08-04 podía limitarse a llamarlo y comprobar el resultado.

La opción -x merece explicación, porque sin ella el toolkit da falsos avisos. bin/informe-diario.sh hace source "$DIR_BASE/lib/comun.sh" (05-06); sin -x, ShellCheck no lee esa librería, no sabe que veloz_log_info existe ni que VELOZ_DIR_DATOS está definida, y emite SC1091 y SC2154. Con -x sigue el source y analiza el conjunto:

El formato tty es para leer; gcc es el que consumen editores, grep y los sistemas de CI.

Cuatro elementos: fichero y línea con la porción exacta subrayada —una misma línea puede acumular varios avisos—; el código SCxxxx, identificador estable que es lo que buscas y lo que silencias; la severidad (error, warning, info, style); y el mensaje, corto y accionable.

Y una cosa que conviene interiorizar: cada código tiene su página de wiki en shellcheck.net/wiki/SC2086, con el problema, ejemplos correctos e incorrectos y las excepciones legítimas. Cuando no entiendas un aviso, esa página es la respuesta; leerla es cómo se aprende Bash de verdad después de un curso.

SC2086 — Double quote to prevent globbing and word splitting. El más frecuente con diferencia, y el problema de 03-06: rm $fichero se rompe con espacios y expande comodines. Corrección: rm "$fichero".

SC2046 — Quote this to prevent word splitting. El mismo problema sobre una sustitución de comandos: chmod 600 $(find . -name '*.conf'). La corrección no es entrecomillar —eso pasaría toda la lista como un único argumento— sino find ... -print0 | xargs -0 chmod 600 (05-01).

SC2006 — Use $(...) instead of legacy backticks. Las comillas invertidas no anidan bien y escapan de forma extraña; la corrección es mecánica.

SC2164 — Use cd ... || exit. Si el cd falla, el script sigue en el directorio anterior y las órdenes destructivas siguientes actúan donde no deben. Corrección: cd "$dir" || veloz_morir 1 "no puedo entrar en $dir".

SC2181 — Check exit code directly with if cmd;, not indirectly with $?. Es 03-04: if grep -q ERROR "$log"; then en lugar de comprobar $? en la línea siguiente. Además de más claro, evita el error clásico de intercalar un echo de depuración que cambia $?.

SC2148 — add a shebang. Falta el #!/usr/bin/env bash de 03-01. En librerías que solo se hacen source no procede un shebang, y ahí la solución es -s bash o la directiva # shellcheck shell=bash.

SC2034 — variable appears unused. Casi siempre es una variable muerta de un refactor; a veces, un falso positivo cuando la consume otro fichero mediante source o un local -n.

SC2155 — Declare and assign separately to avoid masking return values. Sutil y muy importante (04-02):

Con set -e esto pesa mucho: la primera versión no aborta aunque date falle.

SC2016 — Expressions don't expand in single quotes. Suele ser un falso positivo en awk '{print $3}', donde las comillas simples son exactamente lo que quieres; se silencia con una directiva. SC2154 (variable referenciada sin asignar) y SC1090/SC1091 (source no seguible) son típicos de librerías y se resuelven con -x -P lib o con # shellcheck source=lib/comun.sh justo encima del source, que es preferible porque queda documentado en el propio fichero.

A veces ShellCheck se equivoca, o el aviso es correcto pero tú quieres ese comportamiento. La directiva disable tiene tres alcances:

Y un .shellcheckrc en la raíz para las decisiones de equipo, con source-path=lib y external-sources=true. La norma que debe imponerse: toda directiva disable va acompañada de un comentario que la justifique, en la línea inmediatamente anterior. Un disable sin justificar es peor que el aviso original: el aviso al menos era visible y alguien podía investigarlo, mientras que el disable mudo lo entierra y hace creer que el código está revisado. Si silencias algo porque no lo entiendes, has ocultado un bug, no lo has corregido; lee la wiki primero, porque en la inmensa mayoría de los casos el aviso tiene razón.

En 08-01 acordamos un estilo —cuatro espacios, then en la misma línea— y quedó pendiente automatizarlo. shfmt es el formateador de Bash, instalable desde el gestor de paquetes o con go install mvdan.cc/sh/v3/cmd/shfmt@latest.

Con un .editorconfig en la raíz, shfmt toma de ahí la configuración y no hace falta repetir las opciones. El valor en un equipo es doble: elimina la discusión sobre estilo —lo decide el programa— y hace que los diffs de Git contengan solo cambios reales, sin ruido de reindentaciones. Cuidado con una cosa: formatea todo el proyecto una vez, en un commit propio titulado «Formatear el toolkit con shfmt»; mezclar formato y lógica en el mismo commit hace la revisión imposible.

Tres niveles, del más inmediato al más definitivo. En el editor es donde más tiempo se ahorra, porque el aviso aparece mientras escribes: VS Code tiene timonwong.shellcheck y mkhl.shfmt; Vim y Neovim lo integran con ALE o el LSP bash-language-server. En el hook pre-commit (08-04) se impide que entre código con avisos aunque el compañero no tenga la extensión. Y en integración continua, la única barrera que nadie puede saltarse con --no-verify:

Ambos pasos aprovechan el código de salida: ShellCheck devuelve 1 si hay avisos y shfmt -d devuelve 1 si algo no está formateado, así que el trabajo falla solo. -S warning es una decisión consciente: exigimos warning y error, y dejamos info y style como recomendación para no bloquear a nadie por un detalle de forma.

• checkbashisms (paquete devscripts): detecta construcciones de Bash en scripts que declaran #!/bin/sh. Es la herramienta central de la portabilidad y reaparece en 08-07.
• shellharden: reescribe el código añadiendo las comillas que faltan; potente y peligroso a partes iguales. bashate: estilo, más opinado sobre formato que sobre corrección.
• bash -n: no es análisis estático, solo comprobación de sintaxis (05-03), pero es gratis y universal. En el hook va antes de ShellCheck, porque un fichero con un fi de más ni siquiera se puede analizar.

Cuarenta y siete avisos en código que ya habíamos revisado dos veces. Esa cifra es la lección entera: la revisión humana no ve las comillas que faltan.

Los dos SC2115 eran el hallazgo grave: un rm -rf "$VELOZ_DIR_RESPALDO/$fecha" en respaldo.sh donde, si $fecha quedaba vacía por un date fallido, la orden se convertía en rm -rf "/srv/veloz/respaldos/". La corrección es de tres caracteres y evita un desastre:

Con ${var:?} (03-06) el script aborta con un mensaje claro si la variable está vacía, en lugar de borrar la raíz del respaldo. Tras aplicar todo y formatear con shfmt -i 4 -ci -w, shellcheck -x -P lib bin/*.sh lib/comun.sh pasa sin avisos.

• Ejecutar ShellCheck sin -x en un proyecto con librerías. Genera decenas de SC1091 y SC2154 falsos que sepultan los avisos reales.
• Silenciar en masa para «dejarlo limpio». Un .shellcheckrc con diez disable no es código revisado, es código con los avisos apagados.
• Creer que sin avisos el script es correcto. ShellCheck no sabe si tu lógica de negocio está bien; para eso están las pruebas (08-06).
• Ignorar los info por sistema. SC2086 es de severidad info y causa la mitad de los bugs de Bash en producción.
• Consejo: empieza por -S error, luego warning, luego todo. En un script heredado con 200 avisos, ir por severidades hace el trabajo abarcable.
• Consejo: shellcheck.net permite pegar un fragmento y ver los avisos sin instalar nada; nunca con código que contenga datos internos.

Ejercicio 1. Ejecuta mentalmente ShellCheck sobre este fragmento: enumera los avisos con su código y reescríbelo corregido.

Ejercicio 2. ShellCheck avisa de SC2086 en veloz_log_info $mensaje dentro de lib/comun.sh. Explica por qué es un fallo real y no un falso positivo, con un ejemplo concreto de Veloz Envíos.

Ejercicio 3. Escribe el paso de CI que exija a la vez ShellCheck sin avisos de severidad warning o superior y formato shfmt correcto, fallando el trabajo si cualquiera de las dos cosas no se cumple.

Solución 1. Avisos: SC2164 (cd sin control), SC2086 (en $DIR_RESPALDO, $f y $LOG dos veces), SC2006 (comillas invertidas), SC2044/SC2207 (iterar sobre la salida de find) y SC2181 ($? en el if).

El bucle desaparece: find -print0 con xargs -0 (05-01) resuelve a la vez la división de palabras y los nombres con espacios, y -r evita ejecutar rm si no hay ficheros.

Solución 2. Es un fallo real porque el mensaje se construye con datos externos. Con mensaje="incidencia en Palma de Mallorca", la función recibe cinco argumentos en lugar de uno, y si internamente usa $1 el log registrará solo «incidencia». Peor: si el mensaje procede de una línea de acceso.log (08-03) y contiene un *, el globbing lo sustituye por la lista de ficheros del directorio actual y el log queda inservible. La corrección es veloz_log_info "$mensaje", y dentro de la función usar "$*" o "$@" de forma consciente (03-05).

Solución 3.

set -euo pipefail (05-03) detiene el paso en la primera orden que falle; ShellCheck devuelve 1 si encuentra avisos de warning o superior y shfmt -d devuelve 1 si algún fichero no está formateado, así que ambas condiciones se traducen directamente en el resultado del trabajo sin comprobar nada a mano.

ShellCheck es la herramienta con mejor relación entre esfuerzo y beneficio de todo el módulo: analiza el script sin ejecutarlo, tarda menos de un segundo y encuentra exactamente los fallos que Bash nunca señalará, porque el intérprete acepta sin protestar un rm -rf $dir/* que funcionará bien hasta el día en que aparezca un espacio. Se ejecuta sobre los ficheros y devuelve 0 o 1, lo que lo hace automatizable; -x con -P lib es imprescindible en el toolkit para que siga los source de la librería y no llene la salida de SC1091 y SC2154 falsos, -S warning acota la severidad en proyectos heredados y -f gcc produce la salida que consumen editores y CI. Cada aviso trae fichero, línea, fragmento subrayado, severidad y un código SCxxxx con su página de wiki, que es donde de verdad se aprende. Los que más verás ya los conoces por su lección: SC2086 y SC2046 son las comillas de 03-06, SC2164 es el cd sin ||, SC2181 es el $? que debía ser if cmd;, SC2155 es el local x=$(cmd) que enmascara el código de salida de 04-02, SC2148 el shebang de 03-01 y SC1090/SC1091 el source de 05-06. Silenciar es legítimo cuando el aviso es un falso positivo, pero toda directiva disable lleva un comentario que la justifica, porque un disable mudo entierra un bug y aparenta código revisado. shfmt -i 4 -ci -w cierra lo prometido en 08-01 convirtiendo el estilo en una orden en lugar de una discusión, con la ventaja de que los diffs de Git dejan de tener ruido —siempre que el formateo inicial vaya en su propio commit—. La integración se hace en tres niveles: el editor, donde el aviso llega antes de guardar; el hook pre-commit de 08-04; y CI, la única barrera que no se puede saltar. La aplicación al toolkit lo demuestra: 47 avisos en código ya revisado dos veces por humanos, entre ellos un rm -rf que habría borrado la raíz del directorio de respaldos si un date fallaba.

Ahora el toolkit está limpio de errores de forma. Pero ShellCheck no sabe si veloz_porcentaje 0 0 devuelve algo sensato, ni si respaldo.sh conserva de verdad los treinta días de retención, ni si el refactor de rendimiento de 08-02 cambió el contenido del informe. Eso solo lo puede decir una prueba que ejecute el código y compare el resultado con lo esperado. La lección 08-06 introduce Bats: qué merece la pena probar en un script de operaciones, cómo aislar la prueba del entorno con directorios temporales y datos ficticios, cómo sustituir un comando externo por un doble para probar veloz_api_get sin API y respaldo.sh sin tocar el disco, y cómo escribir tests/comun.bats con pruebas reales de las funciones de la librería.