megalinter-check

MegaLinter のチェック

現在の MegaLinter エラーを収集し、megalinter-fix スキルが利用できるコンパクトなエラー一覧を作成します。

モードを選択

• ウォッチモード — 現在のブランチ／PR に対する MegaLinter の CI ジョブが存在する場合（実行中または完了済み）：ログを解析します。Docker は不要です。
• ローカルモード — CI ジョブが利用できない場合、またはユーザーがプッシュ前のチェックを希望する場合：npx mega-linter-runner を使い、Docker で MegaLinter を実行します。
• 対象を絞った再チェック（ローカル、修正後）：以前失敗したリンターのみを、スタンドアロンイメージで並列に再実行します。

ウォッチモード

1. git remote get-url origin と存在する CI 設定ファイルから、プロバイダーを特定します。
2. このスキルのディレクトリから、該当するプロバイダーガイドを読み込みます。必要なものだけを読み込んでください。
   • GitHub Actions → providers/github.md
   • GitLab CI → providers/gitlab.md
   • Azure Pipelines → providers/azure.md
   • Bitbucket Pipelines → providers/bitbucket.md
3. ガイドに従い、MegaLinter ジョブを特定し、実行中であれば完了を待ち、MegaLinter のステップのログを取得します。
4. MegaLinter の概要（❌／✅の表）と、リンターごとのエラーセクションを解析します。
5. MegaLinter がブランチに独自の修正をプッシュしたかどうかを確認します（下記参照）。

MegaLinter の自動修正コミット

APPLY_FIXES と APPLY_FIXES_MODE: commit を使用するリポジトリでは、MegaLinter ジョブが [MegaLinter] Apply linters fixes を件名とするコミット（CI テンプレートの commit_message。リポジトリ側でカスタマイズされている場合は、以下のパターンを調整してください）として、修正を監視対象のブランチにプッシュできます。これには、次の 2 つの影響があります。

• ローカルブランチが遅れているため、その後の作業はまずプルしてから行う必要があります。
• チェックは再実行されません。 CI プロバイダーはワークフローのループを防ぐため、CI トークンによるプッシュを意図的に無視します。そのため、修正を生成した実行の古い結果がブランチに残り、修正によって解決済みであるにもかかわらず、PR のチェックが保留中または失敗のままになることがよくあります。

同じコミットをユーザー自身の認証情報で再プッシュすると、実際のプッシュイベントが発生し、チェックが再トリガーされます。メッセージの先頭に 🤖 を付けて amend するだけで再プッシュでき、履歴上でも再プッシュが分かるようになります。これが、このスキルで強制プッシュが許可される唯一の状況であり、必ず --force-with-lease を使用してください。

検出には Git のみを使用するため、GitHub、GitLab、Azure、Bitbucket のいずれでも同じように動作します。

BRANCH="$(git branch --show-current)"
git fetch origin "$BRANCH"

TIP_SUBJECT="$(git log -1 --format='%s' "origin/$BRANCH")"          # tip commit of the remote branch
LOCAL_AHEAD="$(git rev-list --count "origin/$BRANCH..HEAD")"        # local commits not pushed yet

次の条件をすべて満たす場合に限り amend します。それ以外の場合は何もせず、確認した内容を報告してください。

• TIP_SUBJECT が自動修正のコミット件名であること。その後に別のコミットが追加されている場合は、何もしません。そのプッシュによってチェックはすでに再トリガーされています。
• TIP_SUBJECT がすでに 🤖 で始まっていないこと。以前の実行ですでに amend されており、再度 amend するとループします。
• LOCAL_AHEAD が 0 であること。ローカルにコミットがある場合は、通常どおりプッシュしてください。それだけでチェックが再トリガーされるため、amend は不要です。
• 作業ツリーがクリーンであること（git status --porcelain の出力が空であること）。そうでない場合、以下の fast-forward に失敗するため、先にコミットするか stash してください。
• ブランチがデフォルトブランチではないこと。main／master の場合は、amend と強制プッシュを行う前にユーザーに確認してください。

git merge --ff-only "origin/$BRANCH"                     # fast-forward onto the auto-fix commit
git commit --amend -m "🤖 $(git log -1 --format='%B')"   # keeps the original author, changes the SHA
git push --force-with-lease origin "$BRANCH"             # never --force

プッシュ時にはリモートとブランチを明示してください。引数なしの git push --force-with-lease は、upstream の追跡設定がないブランチでは失敗します。lease は検出手順で更新した origin/<branch> の参照と照合されるため、その間に変更があればプッシュは拒否されます。

その後、コミットを amend してチェックが再トリガーされたことをユーザーに伝え、新しい実行の監視を再開してください。--force-with-lease が拒否された場合は、フェッチ後にリモートが更新されています。--force で再試行するのではなく、最初から検出をやり直してください。

ローカルモード

初めてローカルで実行する前に、MegaLinter をローカルで実行すると多くのリソースを消費することをユーザーに必ず伝えてください。 十分な性能のマシン（CPU、RAM、空きディスク容量）と、安定したインターネット接続が必要です。MegaLinter は Docker ベースであり、初回実行時に大きなイメージ（フレーバーによっては数 GB）をダウンロードします。 そのため、通常はウォッチモード（CI が処理を行う）を推奨します。 両方のモードを選択できる場合（リポジトリに MegaLinter の CI ジョブがある場合、またはジョブを実行するためにブランチや PR をプッシュできる場合）で、ユーザーが明示的に選択していない場合は、ローカルで実行を開始するのではなく、どちらのモードを使うかユーザーに尋ねてください（プラットフォームに構造化された質問の仕組みがある場合は、ウォッチモードを最初に提示し、推奨してください）。

エンジンの事前確認（ローカル実行の前に毎回行う）

実際に応答するコンテナエンジン（docker または podman）が必要です。バイナリがインストールされているだけでは不十分です。バックエンドが停止している場合（例：Docker Desktop の Windows サービス）、失敗をすぐに返さず、docker CLI がいつまでもハングすることがあります。実行を開始する前に、タイムアウトを設定して確認してください：

timeout 10 docker info --format '{{.ServerVersion}}'    # exit 124 = installed but not answering
timeout 10 podman info --format '{{.Version.Version}}'

• 選択したエンジンが応答する → 続行します（podman を使う場合は --container-engine podman を渡します）。
• 選択したエンジンがエラーになる、またはタイムアウトする → 同じ方法でもう一方のエンジンを確認し、応答する場合はそちらを使います。
• どちらも応答しない → 実行を開始しないでください（同じようにハングします）。確認した状況（「Docker Desktop はインストールされているようですが、応答していません。起動していますか？」など）をユーザーに伝え、エンジンをインストールまたは起動するか確認してください。その後（ユーザーの確認を得てから）、セットアップ手順を参照するため、このスキルのディレクトリから container-engine.md を読み込みます（podman を推奨します。企業環境でも無料で利用できます）。ユーザーが希望しない場合は、ウォッチモードに切り替えます。

フレーバーとバージョンは .mega-linter.yml の MEGALINTER_FLAVOR / MEGALINTER_VERSION から自動的に解決されます。自分で --flavor や --release を渡さないでください。

npx mega-linter-runner                            # docker
npx mega-linter-runner --container-engine podman  # podman

ヒント：ローカルで繰り返し実行する場合（例：修正して再確認するループ）は、npm install -g mega-linter-runner でランナーを一度インストールし、mega-linter-runner を直接呼び出してください。実行のたびに発生する npx のパッケージ解決のオーバーヘッドを避けられます。

• .mega-linter.yml で APPLY_FIXES が none 以外に設定されている場合は --fix を追加します（リポジトリで自動修正が有効になっています）。
• ローカルマシンでは並列処理数を制限してください：MegaLinter はデフォルトで CPU コアごとに 1 つのリンタープロセスを並列実行するため、Docker が他のすべてとリソースを共有している開発マシンでは、マシンに過度な負荷がかかる可能性があります。CI ではなくローカルコンピューターで実行する場合（CI／GITHUB_ACTIONS／GITLAB_CI のような環境変数が設定されていない場合）は、全件実行に -e PARALLEL_PROCESS_NUMBER=4 を追加します（コア数が 4 未満の場合は、マシンのコア数を使います）。リポジトリの設定で PARALLEL_PROCESS_NUMBER がすでに設定されている場合は、この指定を省略してください。.mega-linter.yml には絶対に書き込まないでください。CI まで遅くなってしまいます。
• 全件実行には必ず -e JSON_REPORTER=true を追加してください：JSON レポートはデフォルトでは生成されません（JSON_REPORTER のデフォルト値は false です）。この環境変数はリポジトリの設定を上書きし、megalinter-reports/mega-linter-report.json の生成を保証します。
• その後、コンソール出力を解析する代わりに、megalinter-reports/mega-linter-report.json と megalinter-reports/linters_logs/ERROR-*.log を読み込み、保存されたログファイルからコンソールのヒントを抽出します（下記の「コンソールのヒント」を参照）。コンソール出力全体を再読み込みしてヒントを探さないでください。
• レポートファイルが見つからなくても「待つ」必要はありません：ランナーは同期処理です。コマンドが終了した時点でレポートファイルがなければ、その後ファイルが現れることはありません。ポーリング、スリープ、再実行はしないでください。想定したファイルがない場合（リポジトリで REPORT_OUTPUT_FOLDER にカスタムフォルダーや none が設定されている、TEXT_REPORTER: false が設定されている、または TEXT_REPORTER_SUB_FOLDER が異なる場合があります）は、次の順で確認します。.mega-linter.yml の REPORT_OUTPUT_FOLDER を確認し、そのフォルダー以下を **/mega-linter-report.json／**/linters_logs/ で glob します。それでも見つからない場合はコンソール出力を解析してください。❌／✅ のサマリーテーブルとリンターごとのエラーセクションは、常にコンソールに出力されます。

制限時間を設定して実行する — 無期限に待たない

ローカル実行は環境上の理由（エンジンバックエンドの停止、Windows のバインドマウントの停止など。下記参照）でハングすることがあるため、すべてのローカル呼び出し（事前実行、全体実行、対象を絞った再チェック）に明示的な制限時間を設定してください。

1. 利用可能な場合は、まずランナー独自のフラグを使ってください。npx mega-linter-runner --help で --timeout を確認し、記載されている場合は --timeout <seconds> を渡します。時間切れになると、コンテナも停止して削除されます。利用できると決めつけないでください（古いランナーバージョンや固定された MEGALINTER_VERSION では使えない場合があります）。
2. 代替手段として、シェルの coreutils コマンドでラップします — timeout <seconds> npx mega-linter-runner ...。これで終了するのはラッパーだけで、コンテナは終了しません。時間切れになった後は、以下の孤立コンテナのクリーンアップを行ってください。
3. バックグラウンドで起動し、出力をログファイルに保存して、1〜2 分ごとに確認してください。単一のブロッキング呼び出しで無期限に待たないでください。

推奨する制限時間：全体実行は 30 分、事前実行または対象を絞った単一リンターの実行は 10 分 — 中規模のリポジトリで flavor 全体を実行する場合、通常は数時間ではなく数分で終わります。マシンでの初回実行時は、複数 GB のダウンロードで制限時間を使い切らないよう、別途イメージを事前にプルしてください（docker pull <image> / podman pull <image>）。

停止しているのか、単に遅いのか？ 待ち続けずに診断する

ログ出力が約 5 分間ない場合、停止している可能性はありますが、処理中でないとは限りません。積極的に診断してください（<engine> は docker または podman）。

1. <engine> ps -a — コンテナはまだ存在していますか？ また、「Up」になってからどのくらい経っていますか？
2. <engine> logs --tail 30 <name> — 最後の行は何ですか？ 先に進まないフェーズの境界（例："...collects the files to analyse"、"Processing linters on [N] parallel cores"）から、停止箇所が分かります。
3. <engine> exec <name> ps aux — コンテナ内で何が実行されていて、それらのプロセスの累積 CPU TIME は、コンテナの稼働時間と比べてどのくらいですか？ 稼働時間が数時間なのに CPU 時間が数秒なら、実際の計算ではなく I/O の停止です（ファイルシステムまたはネットワーク）。待つのをやめ、実行を停止して、（以下の手順で）クリーンアップし、さらに確認を繰り返すのではなく、診断結果を報告してください。Windows では、よくある原因は WSL2 のバインドマウントによる遅延です。performance.md の「Windows bind-mount slowness」を参照してください。

強制終了後に残る孤立コンテナ

ラップしているコマンド（シェルの timeout の時間切れ、Ctrl-C、npx プロセスの強制終了）を終了しても、特にシグナル転送が不安定な Windows では、コンテナが確実に停止するとは限りません。クリーンアップを保証するのは、ランナー独自の --timeout だけです。強制中断した後は、必ず次の手順を実行してください。

1. <engine> ps -a — megalinter イメージを実行中の、まだ「Up」のコンテナを探します。
2. 該当するコンテナごとに、<engine> stop <name> を実行してから <engine> rm <name> を実行します。

初回のローカル実行：事前分析

リポジトリで初めてローカルの全実行を行う前（megalinter-setup を新規作成した場合、または前回の実行による megalinter-reports/mega-linter-report.json がない場合）は、設定の調整不足で実行を無駄にしないよう、まず事前分析を実施します。また、MegaLinter のパフォーマンス調整をユーザーから依頼された場合も、後から事前分析を実施します。

事前分析には MegaLinter v10 以降または beta が必要です。.mega-linter.yml の MEGALINTER_VERSION を確認し、指定されたバージョンが古い場合は、この手順をスキップして（そのまま全実行に進んで）ください。

1. MegaLinter を分析専用モードで実行します（高速です。リンターは実行されず、直後の実際の実行でもイメージのプルが再利用されます）。

   npx mega-linter-runner --prerun
   

2. megalinter-reports/prerun-report.json を読み込みます。suggestions の各項目には、.mega-linter.yml の変更内容が記載されています。項目は variable、operation（リストへの append／set）、values、safe、reason、details です。

3. ユーザーと提案を確認します。

   • safe: true の提案（gitignore 対象のファイルしか含まないディレクトリ）は、リント対象の範囲を変更しません。まとめて提示し、適用を推奨します。
   • safe: false の提案（よく知られた生成フォルダー名であってもリント可能なファイルを含む場合や、フレーバーの変更）には、ユーザーの明示的な判断が必要です。details に記載されたファイル数を添えて、それぞれについて確認してください。フレーバーを変更する場合は、CI ワークフローファイル内のイメージ参照も更新する必要があります。

4. 承認された変更を .mega-linter.yml に適用してから、通常の全実行に進みます。

実行後にレポートファイルが見つからない場合（MEGALINTER_PRERUN を無視してすべてをリントした v10 より古いイメージを使用した場合）は、再実行せず、出力を通常の全実行として扱います。

対象を絞った再チェック（修正後）

以前失敗した項目だけを、並列（同時実行コンテナーは最大 4 つ）で再実行します。

npx mega-linter-runner --linter PYTHON_RUFF -e JSON_REPORTER=true src/a.py src/b.py &
npx mega-linter-runner --linter MARKDOWN_MARKDOWNLINT -e JSON_REPORTER=true README.md &
wait

（全実行と同じ理由で -e JSON_REPORTER=true を指定します。JSON レポートはデフォルトでは生成されません。）

バージョン規則（すべてのスキルに適用）：ランナーと Docker イメージのバージョンは、常に .mega-linter.yml の MEGALINTER_VERSION に従います。beta の場合は npx mega-linter-runner@beta を呼び出し、それ以外の場合は通常の npx mega-linter-runner を呼び出します。また、--release を自分で渡してはいけません。注意点として、MegaLinter v10 まで、スタンドアロンの megalinter-only-* イメージがマルチアーキテクチャに対応するのは beta タグのみです。MEGALINTER_VERSION が beta 以外で、スタンドアロン実行がプラットフォームエラーで失敗した場合は、その旨をユーザーに伝え、MEGALINTER_VERSION: beta に固定するか、全イメージを使った再チェックに切り替えることを提案してください。

• ファイル単位のリンターには修正済みファイルを引数として渡し、プロジェクト単位のリンター（例：REPOSITORY_*、COPYPASTE_JSCPD）にはファイル一覧を渡しません。
• 各実行のレポートは megalinter-reports/<linter_key_lower>/ に書き込まれるため、並列実行間で競合しません。
• ここでもローカルモードのガードレールが適用されます。最初にエンジンの事前確認を行い、各実行（スタンドアロンリンターごと）を約 10 分以内に制限し、強制終了した場合は残存コンテナーがないか確認します。

出力形式

どのモードでも、結果は次の形式で要約します（これは megalinter-fix が利用します）。

{
  "status": "success|errors|failure",
  "linters": [
    {
      "key": "PYTHON_RUFF",
      "errors": 12,
      "fixable": true,
      "blocking": true,
      "files": ["src/a.py"],
      "samples": ["src/a.py:10:5 E501 line too long"]
    }
  ]
}

ブロック対象のリンター（❌、ジョブ失敗）と、ブロック対象ではないリンター（⚠️、DISABLE_ERRORS: true）を区別します。ステータスが failure の場合は、ジョブ／実行自体に問題が発生しています（コンテナーエンジン、ネットワーク、設定など）。リンターエラーの代わりに、原因の短い抜粋を記した "failure_reason" フィールドを含めます。ウォッチモードでは、参照用に "job_url" フィールドを追加できます。コンソールにヒントが表示された場合は、任意の "tips" フィールドを追加します（下記参照）。

ウォッチモードでは、MegaLinter がブランチに独自の修正をプッシュした場合、任意の "auto_fix_commit" フィールドを追加します。これにより、呼び出し元は作業コピーが最新状態より遅れていること、およびチェックが再実行されたかどうかを把握できます。

"auto_fix_commit": {
  "sha": "94873de",
  "subject": "[MegaLinter] Apply linters fixes",
  "is_branch_tip": true,
  "amended": true
}

コンソールのヒント（実行が成功している場合も）

MegaLinter のコンソール出力には、エージェントに役立つ実行可能なアドバイスが数多く含まれていますが、JSON レポートには反映されません。パフォーマンスに関する警告（「300 を超える .gitignored ファイルがあります……ADDITIONAL_EXCLUDED_DIRECTORIES の設定を検討してください」、「大きなフォルダーが検出されました」）、フレーバーの提案、リンターが実行されなかった理由を説明する [Activation] の通知、非推奨および削除済みリンターの通知、タイムアウトによる終了、除外設定の転送に関するトレースなどです。必ず収集してください。

• ローカルモード：コンソール出力全体はレポートフォルダーに保存されます。megalinter-reports/mega*linter.log を glob で指定してください（ファイル名は LOG_FILE で指定し、既定値は mega-linter.log です。LOG_FILE: none にすると無効になります。その場合は取得したコンソール出力を使用してください）。コンソールを読み直す代わりに、次のコマンドで grep してください：grep -E "⚠|WARNING|\[Activation\]|Heavy folders|To improve|[Ff]lavor|deprecat|Timed out|[Cc]onsider" <log-file>。
• ウォッチモード：CI ジョブログがコンソール出力そのものです。ダウンロードしたログに同じ grep を適用してください。

一致した行から、1 行につき 1 件、最大 10 件にまとめてください。設定、パフォーマンス、アップグレードに関するアクションを提案する行を残し、ファイルごとの lint エラー、バナー、進捗行は除外して、重複を削除してください。次の形式で出力に追加してください。

"tips": [
  "More than 300 .gitignored files detected (612): consider adding directories to ADDITIONAL_EXCLUDED_DIRECTORIES (heaviest: site, coverage)",
  "[Activation] MARKDOWN_RUMDL inactive: set MARKDOWN_DEFAULT_STYLE=rumdl to activate"
]

エラーの概要の後にヒントをユーザーに伝え、設定に関するものは megalinter-setup の改善ステップ、または実行中であれば実行前の提案レビューに反映してください。パフォーマンスに関する提案と同様、ユーザーの同意なしにヒントを適用してはいけません。

パフォーマンスの確認（実行が成功している場合も）

MegaLinter のサマリーテーブルには、リンターごとの Elapsed time 列があります。必ず収集してください。いずれかのリンターの実行時間が30 秒を超えるか、lint の合計時間の25% を超える場合は、出力に "slow_linters" フィールドを追加してください。

"slow_linters": [{"key": "REPOSITORY_GRYPE", "elapsed_seconds": 116.6}]

slow_linters が空でない場合は、このスキルのディレクトリから performance.md を読み込み、該当する改善案をユーザーに報告してください。その際、問題は発生しておらず、純粋に速度を向上させる提案であることを明記してください。ユーザーの同意なしに、パフォーマンスに関する変更（除外、キャッシュ、リンターの無効化）を適用してはいけません。

最適化：サブエージェント（Claude Code および互換性のあるエージェント）

サブエージェントが利用可能で、エージェント定義がインストールされている場合（megalinter-setup を参照）：

MegaLinter がエージェントプラグインとしてインストールされている場合、定義は名前空間付きです（megalinter:megalinter-watcher、megalinter:megalinter-runner、megalinter:megalinter-fixer）。スキルとしてインストールされている場合は、名前空間のない名前のままです。プラットフォームに表示されている形式を使用してください。

• ウォッチモード → ブランチ／PR の参照情報を指定して megalinter-watcher を起動します。ポーリング、取得、解析を行い、出力契約を返します。
• ローカルモード → 実行するコマンドを指定して megalinter-runner を起動します。実行してレポートを分析します。
• 対象を絞った再確認 → 独立したリンターの実行ごとに megalinter-runner を 1 つ起動し、並列実行します（最大 4 つ）。

これにより、数メガバイトに及ぶ CI ログやリンターの出力がコンテキストを圧迫しません。サブエージェントが利用できない場合は、すべてインラインで実行してください。