| name | bash-script-validator |
| type | standard |
| depth | extended |
| description | Validates existing .sh/.bash scripts via ShellCheck 0.11.0+ static analysis, syntax/security/portability checks. Use when debugging SC codes, auditing shell scripts, or checking shell best practices. |
[H1][BASH-SCRIPT-VALIDATOR]
Dictum: Layered validation catches defects that single-pass analysis misses.
Validate bash scripts via syntax check, ShellCheck 0.11.0+ static analysis, and data-driven custom checks.
Tasks:
- Run
bash scripts/validate.sh <script-path> — Syntax, static analysis, custom checks.
- Review errors/warnings/info from output.
- Reference docs/ for fix patterns:
- Suggest fixes — Before/after with line numbers.
[1][VALIDATION_LAYERS]
Dictum: Each layer targets a distinct defect class.
| [INDEX] | [LAYER] | [CHECK] | [TOOL] |
|---|
| [1] | Syntax | bash -n / sh -n | Built-in |
| [2] | Static analysis | SC codes, 4 severity levels (SC2327-SC2335 in 0.11) | ShellCheck 0.11.0+ |
| [3] | Security | eval injection, unsafe rm, pipe-to-shell, dyn source | _SECURITY_CHECKS dispatch table |
| [4] | Performance | UUOC, $(cat) -> $(<), date subshell | _PERF_CHECKS dispatch table |
| [5] | Portability | Bashisms in sh scripts ([[, arrays, source, ==) | _SH_BASHISM_CHECKS dispatch table |
| [6] | Best practice | printf > echo, [[ ]] > [ ], mapfile > while-read | _PRACTICE_CHECKS dispatch table |
Guidance:
- Data-Driven: Custom checks use
declare -Ar tables with "pattern|message|level" format and generic nameref runner.
- Architecture:
_run_check_set() iterates via local -n _checks=$1, splitting each entry with IFS='|' read -r.
[2][EXIT_CODES]
Dictum: Exit codes enable pipeline composition.
| [INDEX] | [CODE] | [MEANING] |
|---|
| [1] | 0 | Clean |
| [2] | 1 | Warnings only |
| [3] | 2 | Errors found |
[3][FILE_MAP]
Dictum: File inventory enables targeted loading.
| [INDEX] | [FILE] | [PURPOSE] |
|---|
| [1] | scripts/validate.sh | Main validator (shebang detection, assoc array counters). |
| [2] | scripts/ensure_shellcheck.sh | Asserts shellcheck presence (Nix-provided; apt/dnf fallback). |
| [3] | docs/shell-reference.md | Bash 5.2+/5.3 vs POSIX sh, FP patterns, data structures. |
| [4] | docs/shellcheck-reference.md | SC codes, v0.11.0 additions, directives, CI. |
| [5] | docs/text-tools.md | rg/sd/awk/regex, bash-native alternatives. |
| [6] | examples/good.sh | Best practices (bash + POSIX). |
| [7] | examples/bad.sh | Anti-patterns (bash + POSIX). |
[REFERENCE]: →shell-reference.md — Language features, FP patterns.
[REFERENCE]: →shellcheck-reference.md — ShellCheck codes, directives.
[REFERENCE]: →text-tools.md — Modern text tools (rg/sd/awk), bash-native alternatives.