bash-portability-linter

Scansiona shell script per costrutti non portabili tra Linux/GNU, macOS/BSD e Git Bash su Windows.

Quando usarlo

• Prima di committare uno script bash che deve girare anche su macOS o Git Bash
• Durante review di PR che modificano file .sh o .bash
• Quando uno script "funziona sul mio Linux" ma un utente Mac segnala errori
• Per controllare skill/plugin Claude Code che includono script shell, dato che molti utenti li eseguono su macOS con bash 3.2

Come invocarlo

Lo skill espone un eseguibile bin/bash-portability-linter:

# Scansione di un singolo file
bash-portability-linter path/to/script.sh

# Scansione ricorsiva di una directory
bash-portability-linter path/to/repo

# Output JSON (per integrazioni CI o post-processing)
bash-portability-linter path/to/repo --json

Exit codes

• 0 — tutto pulito
• 1 — almeno una violazione di severità ERROR
• 2 — solo violazioni di severità WARN

Questo permette di usarlo in un pre-commit hook o in CI con:

bash-portability-linter ./scripts || exit $?

Le 7 regole

Le prime 5 sono ERROR perché lo script esplode subito quando incontra quei costrutti. BP006 e BP007 sono WARN perché lo script parte e si rompe solo sulla linea specifica, quindi sono più facili da aggirare al volo.

Cosa fa il linter internamente

• Usa grep -nE con regex POSIX estese (niente perl, niente python — il linter stesso è bash 3.2 compatible)
• Skippa le linee che sono puri commenti (primo carattere non-whitespace è #)
• In modalità directory usa find per ricorrere, escludendo .git/, node_modules/, e qualsiasi path che contenga tests/fixtures/
• In modalità JSON accumula le violazioni in memoria e emette un singolo oggetto finale con files_scanned, violations[], error_count, warn_count

Origine

Tutte e 7 le regole sono bug reali incontrati mentre costruivo il plugin claude-autopilot su macOS bash 3.2. Ogni volta che una regola catturava un bug mi segnavo il pattern. Dopo 7 regole ho capito che era un linter.

Sviluppo

Questo skill è stato costruito con TDD stretto: RED → GREEN → REFACTOR per ogni regola, una alla volta. La test suite usa bats-core:

bats bash-portability-linter/tests/linter.bats

Include 19 test: uno per ogni regola (con fixture dedicata), più cross-cutting tests per exit code, scansione ricorsiva, output JSON, e un self-lint che esegue il linter su sé stesso per garantire che rimanga bash 3.2 pulito.