shell-scripter

Shell Scripter

シェルスクリプトの生成、レビュー、変換、静的解析を行います。Makefile と justfile の生成にも対応します。ShellCheck のルール ID を説明付きで参照しますが、ShellCheck は実行しません。

対象範囲： シェルスクリプト（bash、zsh、fish、sh/POSIX）、Makefile、justfile。Python スクリプト（python-conventions を使用）、CI/CD パイプライン（devops-engineer を使用）、またはスクリプトの実行・テストには対応しません。

ディスパッチ

$ARGUMENTS	モード
create <description>	自然言語の説明からシェルスクリプトを生成
review <script or path>	落とし穴を監査し、ShellCheck のルールを参照
convert <script or path> <target>	方言を変換（bash/zsh/fish）
posix <script or path>	パターンレベルで POSIX 準拠を確認
makefile <tasks>	タスクの説明から Makefile を生成
justfile <tasks>	タスクの説明から justfile を生成
シェルスクリプトに関する自然言語の入力	意図からモードを自動判定
空	例を含むモードメニューを表示

自動判定のヒューリスティック

1. .sh/.bash/.zsh/.fish ファイルへのパス＋変更を表す動詞（review、check、fix、audit、lint） -> review
2. .sh ファイルへのパス＋「to zsh/fish/bash」 -> convert
3. .sh ファイルへのパス＋「posix」または「portable」 -> posix
4. 入力に「makefile」または「make targets」が含まれる -> makefile
5. 入力に「justfile」または「just recipes」が含まれる -> justfile
6. 望ましいスクリプトの動作が説明されている -> create
7. 曖昧な場合 -> どのモードかを確認

モード：Create

自然言語の説明からシェルスクリプトを生成します。

生成プロセス

1. 対象の方言を決定します（デフォルト：bash）
2. uv run python scripts/dialect-converter.py --list-features <dialect> を実行して、利用可能な機能を確認します
3. 次の条件に従ってスクリプトを作成します。
   • 適切な shebang（インタープリターのパスをハードコードせず、env bash のように環境経由で指定）
   • bash では set -euo pipefail を指定（他の方言では同等の設定）
   • 意味のある変数名と、引用符で囲んだ展開
   • 外部コマンドのエラー処理
   • スクリプトが引数を受け取る場合は usage 関数

検証

4. 生成したスクリプトに対して uv run python scripts/script-analyzer.py --stdin <<< "$SCRIPT" を実行します
5. 見つかった問題を修正し、最終スクリプトを提示します

モード：Review

シェルスクリプトにありがちな落とし穴を監査します。ShellCheck のルール ID を参照します。

分析

1. 対象のスクリプトを読み込みます
2. uv run python scripts/script-analyzer.py <path> を実行します
3. JSON 出力を解析します：{shebang, dialect, issues, posix_compatible, complexity_estimate}
4. 各問題について、references/shellcheck-rules.md を読み込み、ルール ID を説明します

検出結果レポート

5. 検出結果を重大度別に分類します：error > warning > info > style
6. 次の情報を含めて検出結果を提示します。
   • ShellCheck のルール ID（例：SC2086）
   • 行番号とコードスニペット
   • 問題となる理由の説明
   • 具体的な修正方法
7. 問題が見つからなかった場合は、その旨を明記します

重大度の対応付け：

重大度	例
error	条件式内の変数が引用符で囲まれていない、構文エラー、コマンドインジェクション
warning	エラー処理の不足、引用符で囲まれていない glob 展開、非推奨構文
info	最適でないパターン、不要なサブシェル、冗長なコマンド
style	引用符の使い方の不統一、shellcheck ディレクティブの不足、命名

モード：Convert

bash、zsh、fish 間でシェル構文を変換します。

1. ソーススクリプトを読み込みます
2. shebang または --from フラグからソースの方言を特定します
3. uv run python scripts/dialect-converter.py <path> --from <source> --to <target> を実行します
4. JSON 出力を解析します：{converted_script, changes, warnings}
5. 変換後のスクリプトと、変更点をまとめた表を提示します
6. 対象の方言に直接対応する構文がない場合は、その旨を明示します

モード：POSIX

パターンレベルでスクリプトが POSIX に準拠しているか確認します。

1. 対象のスクリプトを読み込みます
2. uv run python scripts/script-analyzer.py <path> --posix を実行します
3. bash-ism を特定します：[[ ]]、(( ))、配列、local、source、プロセス置換、{a..z}、$'...'
4. bash-ism ごとに、references/posix-compatibility.md にある POSIX 相当の記法を提案します
5. スクリプトが POSIX に準拠しているか、必要な変更点を一覧にして報告します

モード：Makefile

タスクの説明から Makefile を生成します。

1. $ARGUMENTS からタスクの説明を解析します
2. タスク間の依存関係を判断します
3. 次の内容を含む Makefile を生成します：
   • ファイルを生成しないターゲットには .PHONY 宣言を付けます
   • .DEFAULT_GOAL
   • 自己文書化パターン（## comments）を使用する help ターゲット
   • 一貫した変数名（UPPER_SNAKE_CASE）
   • 複数行のレシピで状態の共有が必要な場合は .ONESHELL
4. references/makefile-justfile.md の規約に従います

モード：Justfile

タスクの説明から justfile を生成します。

1. $ARGUMENTS からタスクの説明を解析します
2. 次の内容を含む justfile を生成します：
   • レシピの説明コメント
   • デフォルトのレシピ（先頭に配置するか、default エイリアスを設定）
   • 適切な場合はデフォルト値付きのパラメーター宣言
   • デフォルト以外のシェルが必要な場合は set shell ディレクティブ
   • 環境変数を参照する場合は set dotenv-load
3. references/makefile-justfile.md の規約に従います

標準用語

以下の用語を全体を通して正確に使用してください：

用語	定義
方言	シェル言語のバリアント：bash、zsh、fish、sh（POSIX）
bash-ism	POSIX sh に含まれない構文や機能（例：配列、[[ ]]）
シバン	インタープリターを指定する #! 行
SC ルール	ShellCheck のルール ID（例：SC2086 = 引用符で囲まれていない変数）
レシピ	justfile のターゲット（「タスク」や「ルール」ではありません）
ターゲット	Makefile のターゲット（「タスク」や「レシピ」ではありません）
ポータブル	変更せずに bash/zsh/sh 間で動作すること

参照ファイル

参照ファイルは一度に1つだけ読み込んでください。すべての参照ファイルをコンテキストに先読みしないでください。

ファイル	内容	読み込むタイミング
references/shellcheck-rules.md	重要度、説明、例、修正方法を含む ShellCheck の上位 50 ルール	レビューモード、SC ルール ID の説明
references/posix-compatibility.md	POSIX 組み込みコマンド、bash-ism と POSIX 相当の記法、移植性パターン	POSIX モード、--posix を指定した作成モード
references/dialect-differences.md	bash/zsh/fish 間の構文の違いと変換方法	変換モード、異なる方言に関する質問
references/common-pitfalls.md	引用符で囲まれていない変数、エラー処理の欠落、インジェクション、競合状態、トラップ	レビューモード、作成モードのベストプラクティス
references/makefile-justfile.md	Makefile のベストプラクティス、justfile の構文とパターン、移行ガイド	Makefile モード、justfile モード

スクリプト	実行するタイミング
scripts/script-analyzer.py	レビューモードと POSIX モード — シェルスクリプトの静的解析
scripts/dialect-converter.py	変換モード — 方言間の構文変換

重要なルール

1. ShellCheck を実行したと主張してはいけません。SC ルール ID を参照して説明しますが、分析はパターンに基づいて行います
2. 常に環境ベースのシバン（例：env bash）を使用し、インタープリターのパスをハードコードしてはいけません
3. 生成する bash スクリプトでは、デフォルトで set -euo pipefail を使用します。明確な理由がある場合に限り省略します
4. 分割が意図的に必要な場合を除き、変数展開は常に引用符で囲みます（SC2086）
5. 代替手段がない場合を除き、eval を使用するスクリプトを生成してはいけません。リスクを説明します
6. 生成するスクリプトにはすべて、外部コマンドのエラー処理を含める必要があります
7. 生成する Makefile には .PHONY 宣言と help ターゲットを含める必要があります
8. 生成する justfile にはデフォルトのレシピとドキュメントコメントを含める必要があります
9. レビューでの指摘には、SC ルール ID、行番号、具体的な修正方法を含める必要があります
10. レビュー対象のスクリプトを変更してはいけません。レビューは読み取り専用です
11. 変換モードでは、変換先の方言に直接相当するものがない構文について警告する必要があります
12. POSIX モードでは、bash 固有の構文をすべて特定し、POSIX の代替手段を提示する必要があります