bash-script-validator

Bash スクリプトバリデーター

概要

このスキルは、Bash および POSIX シェルスクリプトを段階的なチェックで検証します。

1. 構文検証（bash -n または sh -n）
2. ShellCheck による静的解析（システムのバイナリ、またはラッパーへのフォールバック）
3. セキュリティ、移植性、最適化に関するカスタムチェック

以下のデフォルトフローを使用し、環境に制約がある場合にのみフォールバックに分岐してください。

トリガーの指針

スクリプトの品質、リンティング、構文チェック、またはシェルの移植性に関する作業を依頼された場合は、このスキルを使用してください。

トリガーとなるフレーズ

• 「この bash スクリプトを検証してください」
• 「この .sh ファイルを lint してください」
• 「このシェルスクリプトのセキュリティ上の問題を見つけてください」
• 「このスクリプトが ShellCheck で失敗するのはなぜですか？」
• 「このスクリプトを POSIX 準拠にしてください」
• 「CI の前にこのシェルスクリプトをレビューしてください」

トリガーとならない例

• スクリプトファイルを含まない一般的な Linux コマンドに関する質問
• シェルスクリプトに関係しない Kubernetes、Terraform、またはパイプラインの検証作業
• 純粋な文章の編集作業

決定論的な実行モデル

このスキルのディレクトリからコマンドを実行してください。

cd devops-skills-plugin/skills/bash-script-validator

ステップ 1: 事前確認

1. 対象のパスが存在し、読み取り可能であることを確認します。
2. bash が利用可能であることを確認します。
3. 修正を直接適用できるか（書き込みアクセスがあるか）、提案のみ可能か（読み取り専用か）を確認します。

ステップ 2: ベースライン検証の実行（デフォルトの方法）

bash scripts/validate.sh <script-path>

ステージごとの動作を決定論的にするため、ShellCheck プロバイダーを明示的に設定してください。

# Modes: auto (default), system, wrapper, disabled
VALIDATOR_SHELLCHECK_MODE=system bash scripts/validate.sh <script-path>

以下を記録します。

• 検出されたシェルの種類
• 終了コード（0 は問題なし、1 は警告、2 はエラー）
• 報告されたすべての問題の行番号と、該当する場合は ShellCheck コード（SC####）

ステップ 3: 必要なリファレンスのみを読み込む

問題の種類に応じて段階的に開示します。

• ShellCheck コードの説明：docs/shellcheck-reference.md
• 一般的な修正パターンとセキュリティ上の誤り：docs/common-mistakes.md
• Bash 固有の動作：docs/bash-reference.md
• POSIX への移植性または bashism の修正：docs/shell-reference.md
• テキスト処理の最適化に関する問題：docs/grep-reference.md、docs/awk-reference.md、docs/sed-reference.md、docs/regex-reference.md（直接関係する場合のみ）

ステップ 4: 修正を提示または適用する

問題ごとに、以下を含めてください。

1. バリデーターの出力に基づく正確な位置（行番号とスニペット）
2. 根本原因
3. 修正後のコード
4. 変更によって安全性または移植性が向上する理由
5. 小節レベルの引用（以下の形式）

ファイルのパッチ適用が依頼され、書き込みアクセスがある場合は、問題の種類ごとに小さなまとまりに分けて修正を適用してください。

ステップ 5: 再実行ポリシー（変更後は必須）

編集の各まとまりを適用した後、バリデーターを再実行してください。

bash scripts/validate.sh <script-path>

再実行ループのルール：

1. 新たなエラーが発生しなくなるまで続けます。
2. 意図的に残す警告がある場合は、意図的に許容する理由を記録します。
3. 制約により完全な解決ができない場合は、未解決の項目と明確な次の対応を報告します。
4. 直近の再実行時の終了コードと、残っている問題の数を必ず報告します。

フォールバックの動作

デフォルトのフローをそのまま実行できない場合にのみ、以下の分岐を使用してください。

制約	フォールバックの対応	報告要件
shellcheck が見つからず、ラッパーが利用可能	scripts/validate.sh に scripts/shellcheck_wrapper.sh --cache を自動的に使用させます	ラッパーモードを使用したことを明記します
shellcheck とラッパーの両方が利用不可	構文チェックとカスタムチェックのみを実行します（バリデーターが実行します）	チェック範囲が限定されていることと、ShellCheck による解析が行われていないことを明記します
ラッパーに必要な Python が利用不可	ラッパーの使用を省略し、構文チェックとカスタムチェックは継続します	ShellCheck を実行できなかった理由を明記します
対象ファイルが読み取り専用	編集せず、具体的なパッチ案を提示します	回答に「参考情報のみ」と明記します
対象ファイルが存在しない、または読み取り不可	停止して、有効なファイルパスを求めます	結果を捏造しません
バイナリまたはテキストではない入力	検証を停止します	未対応の入力形式であることを報告します

修正時の引用ガイドライン

重要な修正にはすべて、サブセクションレベルの引用を付けてください。

必須の引用形式：

Reference: docs/<file>.md -> <Section> -> <Subsection>

例：

• 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

引用のルール：

1. 修正の根拠となる、最も具体的なセクションを引用してください。
2. ShellCheck の指摘では、SC#### コードと対応するセクションの両方を含めてください。
3. 正確に一致するサブセクションがない場合は、最も近いセクションを引用し、そのガイダンスから修正を推論したことを明記してください。

応答テンプレート

決定的な出力には、次の構成を使用してください。

• 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:

  <problematic snippet>
  

• Fix:

  <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>

実行例

完全自動化環境

# 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

想定される動作：構文チェック、ShellCheck、カスタムチェックをすべて実行し、結果が安定するまで繰り返し再実行します。

決定的な CI ゲート

# Requires a system shellcheck binary.
bash scripts/run_ci_checks.sh

このランナーは VALIDATOR_REQUIRE_SHELLCHECK=1 および VALIDATOR_SHELLCHECK_MODE=system を強制するため、ShellCheck の段階がスキップされた場合や利用できない場合は CI が失敗します。

制約のある環境（ShellCheck ランタイムなし）

# shellcheck unavailable and wrapper cannot run
bash scripts/validate.sh examples/bad-shell.sh

想定される動作：構文チェックとカスタムチェックは引き続き実行されます。チェック範囲が縮小されることを報告し、ShellCheck が利用可能になった時点で再検証が必要な項目を一覧にします。

バリデータースクリプトの詳細

スクリプト

• scripts/validate.sh：主要なバリデーターのエントリーポイント
• scripts/shellcheck_wrapper.sh：キャッシュされた Python 仮想環境を使用する、任意の ShellCheck フォールバック

検出と実行順序

scripts/validate.sh での検証順序：

1. ファイルチェック（存在すること、読み取り可能であること、テキストファイルであること）
2. シバンに基づくシェルの検出
3. 構文チェック
4. ShellCheck（またはフォールバック／スキップ時の動作）
5. カスタムチェック
6. 終了コードを含むサマリー

終了コード

• 0：問題は見つかりませんでした
• 1：警告が見つかりました
• 2：エラーが見つかりました

参照資料

必要なものだけを読み込んでください。

• 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

完了条件

以下のすべてを満たしたら、このスキルの更新は完了です。

1. 起動条件のガイダンスが明確である（起動する例と起動しない例の両方を含む）。
2. デフォルトのワークフローが決定的な順序で定義されている。
3. ツールがない場合や制約のある環境でのフォールバック動作が明確である。
4. 修正の説明にサブセクションレベルの引用が含まれている。
5. 修正後の再実行が必須であり、終了コードとともに報告される。
6. ドキュメントが完全自動化と制約のある実行の両方をサポートしている。