makefile-validator

Makefile バリデーター

概要

このスキルを使用して、ローカルファーストで決定論的なフローにより Makefile を検証します。

デフォルトのバリデーターのエントリーポイント：

bash scripts/validate_makefile.sh <makefile-path>

検証レイヤー：

1. 依存関係の事前確認（python3、pip3、make）
2. GNU make の構文チェック（make が利用可能な場合は make -n --dry-run）
3. mbake validate
4. mbake format --check
5. カスタムのセキュリティ、ベストプラクティス、最適化チェック
6. インストールされている場合は、オプションで checkmake と unmake のチェック

トリガーの指針

リクエストに Makefile の品質、リンティング、検証、強化、トラブルシューティングが含まれる場合は、このスキルを使用してください。

トリガーフレーズ

• 「この Makefile を検証して」
• 「私の .mk ファイルを lint して」
• 「このビルド用 Makefile の問題を見つけて」
• 「Makefile のセキュリティ問題をチェックして」
• 「CI に入れる前にこの Makefile をレビューして」

トリガーに該当しない例

• ゼロから新しい Makefile を作成する（makefile-generator を使用）
• 納品の一環としてビルドターゲットを実行する
• Makefile に関係しない一般的なシェルスクリプト作業

決定論的な実行モデル

コマンドを短くするには、このスキルのディレクトリから実行します。

cd devops-skills-plugin/skills/makefile-validator

ステップ 1：事前確認

1. 対象ファイルが存在し、読み取り可能であることを確認します。
2. ファイルの編集が許可されているか（writable）、提案のみ返せるか（read-only）を確認します。
3. まずデフォルトのバリデーターパスを優先し、環境上の制約で実行できない場合にのみ代替手段を使用します。

ステップ 2：ベースライン検証（デフォルトパス）

# From skill directory
bash scripts/validate_makefile.sh <makefile-path>

# From repository root
bash devops-skills-plugin/skills/makefile-validator/scripts/validate_makefile.sh <makefile-path>

必ず次の内容を記録します。

• 実行したコマンド
• 終了コード
• 概要の件数（Errors、Warnings、Info）
• ツールが報告した問題の位置

ステップ 3：出力と終了コードの解釈

終了コード	意味	想定される概要行	対応
0	ブロッキング対象の指摘なし	Validation PASSED	改善は任意
1	警告のみ	Validation PASSED with warnings	修正を推奨。マージ方針によります
2	エラーあり	Validation FAILED - errors must be fixed	修正が必要です。修正後に再実行します

ステップ 4：段階的なリファレンスの読み込み

現在の指摘に必要なドキュメントのみ開きます。

指摘の種類	リファレンスドキュメント
.PHONY、.DELETE_ON_ERROR、.ONESHELL、変数の使用、パフォーマンスの構成	docs/best-practices.md
タブとスペース、依存関係の誤り、認証情報のパターン、アンチパターン	docs/common-mistakes.md
mbake の動作、フォーマッターのフラグ、既知の mbake の注意点	docs/bake-tool.md

ステップ 5：修正と再実行のループ

修正を適用した後、再実行します。

bash scripts/validate_makefile.sh <makefile-path>

ループのルール：

1. 新しいエラーが発生しなくなるまで続けます。
2. 意図的に警告を残す場合は、許容する理由を記録します。
3. 必ず最新の再実行の終了コードを報告します。

ドキュメントを開く方法

パスを明確にするため、ファイルを明示的に開くコマンドを使用します。

リポジトリのルートから：

sed -n '1,220p' devops-skills-plugin/skills/makefile-validator/docs/best-practices.md
sed -n '1,220p' devops-skills-plugin/skills/makefile-validator/docs/common-mistakes.md
sed -n '1,220p' devops-skills-plugin/skills/makefile-validator/docs/bake-tool.md
rg -n "PHONY|DELETE_ON_ERROR|ONESHELL|tab|credential|mbake" devops-skills-plugin/skills/makefile-validator/docs/*.md

devops-skills-plugin/skills/makefile-validator から：

sed -n '1,220p' docs/best-practices.md
sed -n '1,220p' docs/common-mistakes.md
sed -n '1,220p' docs/bake-tool.md
rg -n "PHONY|DELETE_ON_ERROR|ONESHELL|tab|credential|mbake" docs/*.md

シェルコマンドが利用できない場合は、同じパスに対して環境のファイルを開く／読み取るアクションを使用します。

フォールバック動作

デフォルトのバリデーターの手順を最後まで実行できない場合にのみ、以下を使用します。

制約	フォールバック時の対応	報告要件
python3 または pip3 が利用できない	限定的なチェックを実行します（make が存在する場合は make -f <file> -n --dry-run を実行し、重点的に grep でチェックします）	mbake の各ステージをスキップし、チェック範囲が縮小していることを明記します
pip3 install mbake が失敗する（オフライン／プロキシ／インデックスの問題）	実行可能な構文チェック／カスタムチェックは継続し、フォーマッター／リンターステージは保留します	インストールの失敗を報告し、ネットワークが利用可能な環境で再実行するよう依頼します
make が利用できない	構文以外のステージを続行します。スクリプトは構文ステージをすでにダウングレードしています	構文チェックをスキップしたことを明記します
checkmake または unmake が利用できない	続行します。これらは任意のステージです	任意のリンター／移植性チェックを実行していないことを明記します
対象ファイルが読み取り専用	パッチの提案のみを提示します	回答が助言のみであることを明記します
コマンドを実行できない	ファイルの内容とドキュメントに基づく静的レビューを提示します	結果が未実行の分析であることを明記します

最小限のフォールバックコマンド：

# Syntax only (when make exists)
make -f <makefile-path> -n --dry-run

# Focused quick checks
grep -n "^\\.DELETE_ON_ERROR:" <makefile-path>
grep -n "^\\.PHONY:" <makefile-path>
grep -nE "^(  |    |        )[a-zA-Z@\\$\\(]" <makefile-path>

終了コードに対応する結果の例

問題なし（exit 0）

Errors:   0
Warnings: 0
Info:     2
✓ Validation PASSED

警告のみ（exit 1）

Errors:   0
Warnings: 3
Info:     1
⚠ Validation PASSED with warnings

エラーあり（exit 2）

Errors:   2
Warnings: 1
Info:     0
⚠ Validation FAILED - errors must be fixed

トラブルシューティングのクイックスタート

1. 必須ツールを確認します：

command -v python3 pip3 make

2. GNU make の構文エラーを切り分けます：

make -f <makefile-path> -n --dry-run

3. タブによるインデント違反の可能性を確認します：

grep -nE "^(  |    |        )[a-zA-Z@\\$\\(]" <makefile-path>

4. プレーンな出力でバリデーターを再実行し、ログを保存します：

NO_COLOR=1 bash scripts/validate_makefile.sh <makefile-path> > /tmp/makefile-validator.log 2>&1
echo "exit=$? log=/tmp/makefile-validator.log"

5. mbake のインストールが引き続き失敗する場合は、ネットワークが利用可能なシェルまたは内部 PyPI ミラーを使って検証し、その後バリデーター全体を再実行します。

スキルのパス

makefile-validator/
├── SKILL.md
├── scripts/
│   └── validate_makefile.sh
├── docs/
│   ├── best-practices.md
│   ├── common-mistakes.md
│   └── bake-tool.md
└── examples/
    ├── good-makefile.mk
    └── bad-makefile.mk

完了条件

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

1. トリガーに関するガイダンスが明確で、簡単に確認できます。
2. 実行フローが決定的です（事前確認 -> 実行 -> 結果の解釈 -> ドキュメント -> 再実行）。
3. 「ドキュメントを開く方法」の説明に、正確なコマンドとパスが含まれています。
4. 結果の例が終了コード（0、1、2）に明示的に対応付けられています。
5. ツールが利用できない場合や環境に制約がある場合のフォールバック動作が記載されています。
6. トラブルシューティングのクイックスタートが簡潔で、実行可能です。
7. Frontmatter の name と description は変更されていません。