bash-script-validator

# Bash Script Validator ## Overview This skill validates Bash and POSIX shell scripts with layered checks: 1. Syntax validation (`bash -n` or `sh -n`) 2. ShellCheck static analysis (system binary or wrapper fallback) 3. Custom security, portability, and optimization checks Use the default flow below, then branch to fallbacks only when the environment is constrained. ## Trigger Guidance Use this skill when the request includes script quality, linting, syntax checking, or shell portability work. ### Trigger Phrases - "Validate this bash script" - "Lint this `.sh` file" - "Find security issues in this shell script" - "Why does this script fail ShellCheck?" - "Make this script POSIX compliant" - "Review this shell script before CI" ### Non-Trigger Examples - General Linux command questions with no script file - Kubernetes, Terraform, or pipeline validation tasks that do not involve shell scripts - Pure prose editing tasks ## Deterministic Execution Model Run commands from this skill directory: ```bash cd devops-skills-plugin/skills/bash-script-validator ``` ### Step 1: Preflight 1. Confirm target path exists and is readable. 2. Confirm `bash` is available. 3. Determine whether fixes can be applied directly (write access) or only suggested (read-only). ### Step 2: Run Baseline Validation (Default Path) ```bash bash scripts/validate.sh <script-path> ``` For deterministic stage behavior, set the ShellCheck provider explicitly: ```bash # Modes: auto (default), system, wrapper, disabled VALIDATOR_SHELLCHECK_MODE=system bash scripts/validate.sh <script-path> ``` Record: - Detected shell type - Exit code (`0` clean, `1` warnings, `2` errors) - All reported issue lines and ShellCheck codes (`SC####`) when present ### Step 3: Load Only Needed References Progressive disclosure by issue type: - ShellCheck code explanations: `docs/shellcheck-reference.md` - General fix patterns and security mistakes: `docs/common-mistakes.md` - Bash-only behavior: `docs/bash-reference.md` - POSIX portability or bashism fixes: `docs/shell-reference.md` - Text-processing optimization issues: `docs/grep-reference.md`, `docs/awk-reference.md`, `docs/sed-reference.md`, `docs/regex-reference.md` (only when directly relevant) ### Step 4: Provide or Apply Fixes For each issue, include: 1. Exact location from validator output (line number and snippet) 2. Root cause 3. Corrected code 4. Why the change is safer or more portable 5. Subsection-level citation (format below) If the request includes patching files and write access is available, apply fixes in small batches grouped by issue type. ### Step 5: Rerun Policy (Mandatory After Changes) After each batch of edits, rerun the validator: ```bash bash scripts/validate.sh <script-path> ``` Rerun loop rules: 1. Continue until no new errors are introduced. 2. If warnings remain by design, document why they are intentionally accepted. 3. If constraints prevent full resolution, report unresolved items with a clear next action. 4. Always report the latest rerun exit code and remaining issue count. ## Fallback Behavior Use these branches only when the default flow cannot run as-is. | Constraint | Fallback action | Reporting requirement | | --- | --- | --- | | `shellcheck` missing, wrapper available | Let `scripts/validate.sh` use `scripts/shellcheck_wrapper.sh --cache` automatically | State that wrapper mode was used | | `shellcheck` and wrapper unavailable | Run syntax + custom checks only (validator does this) | Explicitly call out reduced coverage and missing ShellCheck analysis | | Python unavailable for wrapper | Skip wrapper path, keep syntax + custom checks | State why ShellCheck could not run | | Target file is read-only | Provide precise patch suggestions without editing | Mark response as "advisory only" | | Target file missing or unreadable | Stop and request a valid file path | Do not fabricate results | | Binary/non-text input | Stop validation | Report unsupported input type | ## Citation Guidance for Fixes Use subsection-level citations for every non-trivial fix. Required citation format: ```text Reference: docs/<file>.md -> <Section> -> <Subsection> ``` Examples: - `Reference: docs/common-mistakes.md -> 1. Unquoted Variables -> Solution` - `Reference: docs/shellcheck-reference.md -> SC2164: Use || exit After cd` - `Reference: docs/shell-reference.md -> POSIX Best Practices -> 5. Avoid Bashisms` Citation rules: 1. Cite the most specific section that justifies the fix. 2. For ShellCheck findings, include both the `SC####` code and the matching section. 3. If no exact subsection exists, cite the closest section and state that the fix is inferred from that guidance. ## Response Template Use this structure for deterministic output: - `Validation Results` - `Command`: `bash scripts/validate.sh <script-path>` - `Detected shell`: `<shell>` - `Exit code`: `<code>` - `Summary`: `<errors> errors, <warnings> warnings, <info> info` - `Issue`: `<short label> (Line <n>)` - `Problem`: ```bash <problematic snippet> ``` - `Fix`: ```bash <corrected snippet> ``` - `Why`: `<short explanation>` - `Reference`: `docs/<file>.md -> <Section> -> <Subsection>` - `Rerun command`: `bash scripts/validate.sh <script-path>` - `Exit code after fixes`: `<code>` - `Remaining issues`: `<count or none>` ## Example Flows ### Fully Automated Environment ```bash # 1) Baseline validation bash scripts/validate.sh examples/bad-bash.sh # 2) Apply fixes to target script # 3) Rerun validation bash scripts/validate.sh examples/bad-bash.sh ``` Expected behavior: full syntax + ShellCheck + custom-check coverage, with iterative reruns until stable. ### Deterministic CI Gate ```bash # Requires a system shellcheck binary. bash scripts/run_ci_checks.sh ``` This runner enforces `VALIDATOR_REQUIRE_SHELLCHECK=1` and `VALIDATOR_SHELLCHECK_MODE=system` so CI fails if the ShellCheck stage is skipped or unavailable. ### Constrained Environment (No ShellCheck Runtime) ```bash # shellcheck unavailable and wrapper cannot run bash scripts/validate.sh examples/bad-shell.sh ``` Expected behavior: syntax + custom checks still run. Report reduced coverage and list what must be revalidated once ShellCheck is available. ## Validator Script Details ### Scripts - `scripts/validate.sh`: primary validator entrypoint - `scripts/shellcheck_wrapper.sh`: optional ShellCheck fallback using a cached Python virtual environment ### Detection and Ordering Validation order in `scripts/validate.sh`: 1. File checks (exists/readable/text) 2. Shebang-based shell detection 3. Syntax check 4. ShellCheck (or fallback/skip behavior) 5. Custom checks 6. Summary with exit code ### Exit Codes - `0`: no issues found - `1`: warnings found - `2`: errors found ## References Load only what is needed: - `docs/bash-reference.md` - `docs/shell-reference.md` - `docs/shellcheck-reference.md` - `docs/common-mistakes.md` - `docs/grep-reference.md` - `docs/awk-reference.md` - `docs/sed-reference.md` - `docs/regex-reference.md` ## Done Criteria This skill update is complete when all are true: 1. Trigger guidance is explicit (positive and non-trigger examples). 2. Default workflow is deterministic and ordered. 3. Fallback behavior is explicit for missing tooling and constrained environments. 4. Fix explanations include subsection-level citations. 5. Post-fix rerun policy is mandatory and reported with exit codes. 6. Documentation supports both fully automated and constrained execution paths. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/akin-ozer) — claim your Tome and manage your conversions. <!-- tomevault:4.0:skill_md:2026-04-11 -->