zshshellcheck 0.2.1

A static analysis tool for zsh shell scripts

ZshCheck

Uma ferramenta de análise estática para scripts zsh, construída com Python 3.12+.

Funcionalidades

• Parser Tree-sitter: Análise AST precisa usando gramática tree-sitter-zsh
• Checks Plugin-based: Sistema de verificação extensível com padrão registry
• CLI Rico: Saída formatada com tabela, JSON e formatos compactos
• Múltiplos Formatos de Saída: Table, JSON e compacto
• Auto-Fix: Corrige automaticamente problemas detectáveis (--fix flag)
• Suporte a Unicode: Aceita emojis e caracteres não-ASCII em comentários

Instalação

pip install zshshellcheck

Início Rápido

# Analisar um script
zshcheck script.zsh

# Analisar múltiplos arquivos
zshcheck *.zsh

# Listar checks disponíveis
zshcheck --list-checks

# Filtrar por código de check
zshcheck --include ZC1001 --include ZC2001

# Saída em JSON
zshcheck --format json script.zsh

# Auto-fixar problemas (pergunta para cada fix)
zshcheck script.zsh --fix

# Ou usando a flag curta
zshcheck script.zsh -F

Documentação

A documentação completa está disponível em: https://developer.github.io/zshshellcheck/

Limitações Conhecidas

Emojis e Unicode em scripts zsh

O parser tree-sitter-zsh pode apresentar problemas com caracteres unicode em identificadores (nomes de variáveis, funções). Esses caracteres agora são detectados como INFO (ZC9004) em vez de erro, para que você possa decidir se quer ajustar.

Exemplo de warning:

INFO  ZC9004  Non-ASCII characters detected (2 found). Found: 'ã' 'é'

Isso aparece como INFO (não blockea a análise) e indica quais caracteres foram encontrados.

Sintaxe zsh avançada

Algumas sintaxes zsh avançadas (como parâmetros de glob qualifiers ${(k)functions}) podem não ser suportadas pelo parser. Recomendamos usar a flag acima para scripts que contenham dessas expressões.

Desenvolvimento

# Executar testes
pytest -v

# Executar linting
ruff check .

# Executar type checking
mypy .

# Verificação completa
ruff check . && mypy . && pytest

Licença

MIT