Configuração e Análise Estática do ShellCheck

Orientação abrangente para configurar e usar o ShellCheck para melhorar a qualidade de scripts shell, identificar armadilhas comuns e impor melhores práticas através de análise estática de código.

Não use esta habilidade quando

• A tarefa não estiver relacionada à configuração e análise estática do shellcheck
• Você precisar de um domínio ou ferramenta diferente fora deste escopo

Instruções

• Clarifique objetivos, restrições e entradas necessárias.
• Aplique melhores práticas relevantes e valide os resultados.
• Forneça etapas acionáveis e verificação.

Use esta habilidade quando

• Configurando linting para scripts shell em pipelines de CI/CD
• Analisando scripts shell existentes em busca de problemas
• Entendendo códigos de erro e avisos do ShellCheck
• Configurando o ShellCheck para requisitos específicos do projeto
• Integrando o ShellCheck em fluxos de trabalho de desenvolvimento
• Suprimindo falsos positivos e configurando conjuntos de regras
• Impondo padrões consistentes de qualidade de código
• Migrando scripts para atender a portões de qualidade

Fundamentos do ShellCheck

O que é ShellCheck?

ShellCheck é uma ferramenta de análise estática que analisa scripts shell e detecta padrões problemáticos. Ele suporta:

• Bash, sh, dash, ksh e outros shells POSIX
• Mais de 100 avisos e erros diferentes
• Configuração para o shell e flags de destino
• Integração com editores e sistemas de CI/CD

Instalação

# macOS with Homebrew
brew install shellcheck

# Ubuntu/Debian
apt-get install shellcheck

# From source
git clone https://github.com/koalaman/shellcheck.git
cd shellcheck
make build
make install

# Verify installation
shellcheck --version

Arquivos de Configuração

.shellcheckrc (Nível do Projeto)

Crie .shellcheckrc na raiz do seu projeto:

# Specify target shell
shell=bash

# Enable optional checks
enable=avoid-nullary-conditions
enable=require-variable-braces

# Disable specific warnings
disable=SC1091
disable=SC2086

Variáveis de Ambiente

# Set default shell target
export SHELLCHECK_SHELL=bash

# Enable strict mode
export SHELLCHECK_STRICT=true

# Specify configuration file location
export SHELLCHECK_CONFIG=~/.shellcheckrc

Códigos de Erro Comuns do ShellCheck

SC1000-1099: Erros de Parse

# SC1004: Backslash continuation not followed by newline
echo hello\
world  # Error - needs line continuation

# SC1008: Invalid data for operator `=='
if [[ $var =  "value" ]]; then  # Space before ==
    true
fi

SC2000-2099: Problemas do Shell

# SC2009: Consider using pgrep or pidof instead of grep|grep
ps aux | grep -v grep | grep myprocess  # Use pgrep instead

# SC2012: Use `ls` only for viewing. Use `find` for reliable output
for file in $(ls -la)  # Better: use find or globbing

# SC2015: Avoid using && and || instead of if-then-else
[[ -f "$file" ]] && echo "found" || echo "not found"  # Less clear

# SC2016: Expressions don't expand in single quotes
echo '$VAR'  # Literal $VAR, not variable expansion

# SC2026: This word is non-standard. Set POSIXLY_CORRECT
# when using with scripts for other shells

SC2100-2199: Problemas de Aspas

# SC2086: Double quote to prevent globbing and word splitting
for i in $list; do  # Should be: for i in $list or for i in "$list"
    echo "$i"
done

# SC2115: Literal tilde in path not expanded. Use $HOME instead
~/.bashrc  # In strings, use "$HOME/.bashrc"

# SC2181: Check exit code directly with `if`, not indirectly in a list
some_command
if [ $? -eq 0 ]; then  # Better: if some_command; then

# SC2206: Quote to prevent word splitting or set IFS
array=( $items )  # Should use: array=( $items )

SC3000-3999: Problemas de Conformidade POSIX

# SC3010: In POSIX sh, use 'case' instead of 'cond && foo'
[[ $var == "value" ]] && do_something  # Not POSIX

# SC3043: In POSIX sh, use 'local' is undefined
function my_func() {
    local var=value  # Not POSIX in some shells
}

Exemplos Práticos de Configuração

Configuração Mínima (POSIX Estrito)

#!/bin/bash
# Configure for maximum portability

shellcheck \
  --shell=sh \
  --external-sources \
  --check-sourced \
  script.sh

Configuração de Desenvolvimento (Bash com Regras Flexíveis)

#!/bin/bash
# Configure for Bash development

shellcheck \
  --shell=bash \
  --exclude=SC1091,SC2119 \
  --enable=all \
  script.sh

Configuração de Integração CI/CD

#!/bin/bash
set -Eeuo pipefail

# Analisa todos os scripts shell e falha em caso de problemas
find . -type f -name "*.sh" | while read -r script; do

…