pr-gfm-validator

PR GFM リンクバリデーター

プルリクエストの説明文に含まれる GFM リンクを検証し、自動変換して 404 エラーを防ぎます。

自己進化型スキル：このスキルは使用を通じて改善されます。手順に誤りがある、パラメーターが変化している、または回避策が必要になった場合は、先延ばしにせず、すぐにこのファイルを修正してください。更新するのは、実際に再現可能な問題がある場合に限ります。

このスキルを使用する場面

このスキルは次の場合に起動します。

• フィーチャーブランチからプルリクエストを作成する
• PR の説明文または本文の内容について話し合う
• GFM リンク、PR リンク、またはリンク検証に言及する
• gh pr create または gh pr edit を使用する

問題

PR の説明文にあるリポジトリ相対リンクは、フィーチャーブランチではなくベースブランチ（main）を参照します。

PR 本文のリンク	GitHub による解決先	結果
[ADR](/docs/adr/file.md)	/blob/main/docs/adr/file.md	404（ファイルはフィーチャーブランチにのみ存在）

解決策

リポジトリ相対リンクを、正しいブランチを含む絶対 blob URL に変換します。

/docs/adr/file.md
    ↓
https://github.com/{owner}/{repo}/blob/{branch}/docs/adr/file.md

---

ワークフロー

ステップ 1：コンテキストを確認する

PR に関する操作の前に、リポジトリのコンテキストを収集します。

/usr/bin/env bash << 'PREFLIGHT_EOF'
# Get repo owner and name
gh repo view --json nameWithOwner --jq '.nameWithOwner'

# Get current branch
git rev-parse --abbrev-ref HEAD

# Check if on feature branch (not main/master)
BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [[ "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
  echo "On default branch - no conversion needed"
  exit 0
fi
PREFLIGHT_EOF

ステップ 2：変換するリンクを特定する

PR 本文をスキャンし、次のパターンに一致する GFM リンクを探します。

変換するパターン：

• /path/to/file.md - リポジトリルートからの相対パス
• ./relative/path.md - カレントディレクトリからの相対パス
• ../parent/path.md - 親ディレクトリからの相対パス

スキップするパターン：

• https://... - すでに絶対 URL
• http://... - すでに絶対 URL
• #anchor - ページ内アンカー
• mailto:... - メールリンク

ステップ 3：Blob URL を組み立てる

変換するリンクごとに、次のようにします。

# Pattern
f"https://github.com/{owner}/{repo}/blob/{branch}/{path}"

# Example
owner = "example-org"
repo = "research-repo"
branch = "feat/2025-12-01-eth-block-metrics"
path = "docs/adr/2025-12-01-file.md"

# Result
"https://github.com/example-org/research-repo/blob/feat/2025-12-01-eth-block-metrics/docs/adr/2025-12-01-file.md"

ステップ 4：変換を適用する

PR 本文内で特定したリンクをすべて置き換えます。

# Before

[Plugin Design](/docs/adr/2025-12-01-slug.md)

# After

[Plugin Design](https://github.com/example-org/research-repo/blob/feat/branch/docs/adr/2025-12-01-slug.md)

ステップ 5：結果を検証する

変換後、次の点を確認します。

1. すべてのリポジトリ相対リンクが絶対 blob URL になっている
2. 外部リンクが変更されていない
3. アンカーリンクが変更されていない

---

gh pr create との連携

PR を作成する際は、このワークフローを自動的に適用します。

/usr/bin/env bash << 'GIT_EOF'
# 1. Get context
REPO_INFO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
OWNER=$(echo "$REPO_INFO" | cut -d'/' -f1)
REPO=$(echo "$REPO_INFO" | cut -d'/' -f2)
BRANCH=$(git rev-parse --abbrev-ref HEAD)

# 2. Process PR body (convert links)
# ... link conversion logic ...

# 3. Create PR with converted body
gh pr create --title "..." --body "$CONVERTED_BODY"
GIT_EOF

---

リンク検出用正規表現

GFM リンクを見つけるには、次の正規表現パターンを使用します。

\[([^\]]+)\]\((/[^)]+|\.\.?/[^)]+)\)

内訳：

• \[([^\]]+)\] - リンクテキストをキャプチャ
• \( - 開き括弧
• (/[^)]+|\.\.?/[^)]+) - /、./、または ../ で始まるパスをキャプチャ
• \) - 閉じ括弧

---

例

例 1：シンプルなリポジトリ相対リンク

入力：

See the [ADR](/docs/adr/2025-12-01-eth-block-metrics.md) for details.

コンテキスト：

• Owner：example-org
• Repo：research-repo
• Branch：feat/2025-12-01-eth-block-metrics-data-plugin

出力：

See the [ADR](https://github.com/example-org/research-repo/blob/feat/2025-12-01-eth-block-metrics-data-plugin/docs/adr/2025-12-01-eth-block-metrics.md) for details.

例 2：複数のリンク

入力：

## References

- [Plugin Design](/docs/adr/2025-12-01-slug.md)
- [Probe Integration](/docs/adr/2025-12-02-slug.md)
- [External Guide](https://example.com/guide)

出力：

## References

- [Plugin Design](https://github.com/example-org/research-repo/blob/feat/branch/docs/adr/2025-12-01-slug.md)
- [Probe Integration](https://github.com/example-org/research-repo/blob/feat/branch/docs/adr/2025-12-02-slug.md)
- [External Guide](https://example.com/guide)

注：外部リンクは変更されていません。

例 3：認証情報ファイルへのリンク

入力：

**See [`.env.clickhouse`](/.env.clickhouse)** for credentials.

出力：

**See [`.env.clickhouse`](https://github.com/example-org/research-repo/blob/feat/branch/.env.clickhouse)** for credentials.

---

エッジケース

すでに main/master 上にいる場合

• 変換をすべてスキップする
• リポジトリ相対リンクは正しく機能します

PR 本文が空の場合

• 変換するものはありません
• PR の作成に進みます

GFM リンクが見つからない場合

• 変換するものはありません
• PR の作成に進みます

リンクの種類が混在している場合

• リポジトリ相対リンクのみを変換する
• 外部 URL、アンカー、mailto リンクはそのまま保持する

---

変更後のチェックリスト

このスキルを変更した後は、次の点を確認してください。

1. 正規表現パターンが意図したリンク形式に引き続き一致する
2. 例が現在の動作を反映している
3. エッジケースが記載されている
4. ワークフローの手順を実行できる

---

参考資料

• GitHub Blob URL
• GFM リンク構文
• gh CLI ドキュメント

---

トラブルシューティング

問題	原因	解決策
PR 後もリンクが 404 になる	ファイルがまだブランチにプッシュされていない	PR を作成する前にコミットをプッシュします
正規表現がリンクに一致しない	コンテンツ内の括弧がエスケープされている	生の文字列の正規表現パターンを使用します
ブランチ名にスラッシュが含まれる	URL エンコードが必要	URL の構築時にブランチ名をエンコードします
外部リンクが変換される	パターンの範囲が広すぎる	リンクが /、./、../ のいずれかで始まる場合のみ対象にします
gh repo view が失敗する	Git リポジトリ内にいない	リポジトリのルートディレクトリから実行します
アンカーリンクが壊れている	スキャン対象に誤って含められている	# で始まるリンクを除外します
誤ったリポジトリが検出される	リモートが正しく設定されていない	git remote -v の出力を確認します
変換が重複する	バリデーターを 2 回実行している	変換前にリンクがすでに絶対パスになっているか確認します

実行後の振り返り

このスキルの完了後、タスクを終了する前に振り返りを行います。

0. 現在位置を確認します。 — 編集する前に、この SKILL.md の正規パスを確認します。
1. 何が失敗しましたか？ — 原因となった指示を修正します。
2. 予想以上にうまくいったことは何ですか？ — 推奨されるプラクティスとして取り入れます。
3. 実態とずれていることは何ですか？ — 現状と一致しなくなったスクリプト、参照先、依存関係を修正します。
4. 記録します。 — 発生のきっかけ、修正内容、根拠を含む進化ログのエントリーを追加します。

先送りしてはいけません。次の実行では、あなたが残した状態が引き継がれます。