verify-timeline-event-coverage

Files (1)

• SKILL.md

SKILL.md (first lines)

# verify-timeline-event-coverage

このリポジトリ (`gh-timeline`) は GitHub の GraphQL union を 2 つ網羅する:

- `PullRequestTimelineItems` (PR timeline 用)
- `IssueTimelineItems` (Issue timeline 用)

GitHub は schema を不定期に更新する。新規 event 追加・既存 field の変更・deprecate
が起きると、本リポジトリの宣言と乖離して dispatcher fallback に落ちたり、
そもそも query が schema error で落ちる可能性がある。

このスキルは **その差分検出 → 修正 → 検証** までを段階的に案内する。

## 起動の判断基準

以下のいずれかが当てはまれば本スキルを invoke する:

- ユーザーが「timeline event coverage」「schema audit」「新しい event 対応」等を依頼
- `coverage_test.go` の `TestDispatchCoverage_*` が fail
- Live で `gh timeline` を叩いたら未知の `__typename` が頻発
- gh-timeline の major release 前の最終チェック
- GitHub の changelog / blog で timeline event 系の追加・変更が観測された

## 全体フロー

```
[Step 1: Schema diff]
        ↓
[Step 2: Triage]  ← 人間判断ポイント
        ↓
[Step 3: Patch code]
        ↓
[Step 4: Update tests]
        ↓
[Step 5: Live verification]  ← 人間判断ポイント
        ↓
[Step 6: (任意) Fixture refresh]  ← PLAN.md へ委譲
```

⚠️ マーク = 人間の判断や手動操作が必要な箇所。

## Step 1: Schema diff

GitHub の現行 union member を introspection で取得し、本リポジトリの宣言と比較する。

```sh
# 作業ディレクトリへ移動
cd "$(git rev-parse --show-toplevel)"

# 1.1 GitHub schema 側の union member
gh api graphql -f query='
query {
  pr: __type(name: "PullRequestTimelineItems") { possibleTypes { name } }
  issue: __type(name: "IssueTimelineItems") { possibleTypes { name } }
}' --jq '.data.pr.possibleTypes[].name'    | sort -u > /tmp/pr_upstream.txt
gh api graphql -f query='
query { issue: __type(name: "IssueTimelineItems") { possibleTypes { name } } }
' --jq '.data.issue.possibleTypes[].name'  | sort -u > /tmp/issue_upstream.txt

# 1.2 本 repo 側の宣言 (graphql tag を抽出)
grep -hE '`graphql:"\.\.\. on [A-Za-z0-9]+"`' internal/timeline/query.go \
  | grep -oE 'on [A-Za-z0-9]+' | sed 's/^on //' | sort -u > /tmp/repo_declared.txt

# 1.3 PR union の差分 — 本 repo は両 union 分を 1 ファイルに宣言しているので
#     pr_upstream に対してのみ厳密チェック (issue union は subset)
echo "== upstream PR にあって repo に無い (新規対応が必要) =="
comm -23 /tmp/pr_upstream.txt /tmp/repo_declared.txt

echo "== repo に宣言があるが upstream PR に無い (deprecated 検証) =="
comm -13 /tmp/pr_upstream.txt /tmp/repo_declared.txt | grep -v -E '^(Issue|PullRequest)$'

echo "== issue union の追加分 (PR 共通でない場合) =="
comm -23 /tmp/issue_upstream.txt /tmp/pr_upstream.txt
```

## Step 2: Triage ⚠️ 人間判断

Step 1 の結果を 4 つに分類する。

| 差分カテゴリ          | 内容                                   | 対処                                                                                                                            |
| --------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| (A) 新規追加          | upstream にあって repo にない typename | Step 3 で fragment + dispatch case + handler を追加                                                                             |
| (B) 削除 (deprecated) | repo にあって upstream にない typename | Step 3 で fragment / case / handler を撤去。Projects classic 系は EOL 後しばらく schema には残ることがある — GitHub Docs で確認 |
| (C) フィールド変更    | typename は同じだが field が変わった   | introspection だけだと検出不可。**GitHub Docs / Changelog で event 型の field 一覧を目視確認**                                  |
| (D) 命名変更          | A と B の両方に同時出現                | 既存 fragment / case を rename で対応                                                                                           |

⚠️ **人間判断が要るところ:**

- B の場合: 本当に削除して良いか (関連 reference fixture が壊れないか) を判断
- C の場合: 既存 fragment が必要な field を取り続けているかを Docs で確認
- D の場合: rename と削除の見分けは Docs / Changelog 必須
- 「summary 文言をどう書くか」(API では決まらない設計判断)

## Step 3: Patch code

新規 event `<FooEvent>` 1 つにつき以下を実施:

### 3.1 Fragment 追加 (`internal/timeline/nodes.go`)

actor + createdAt しか使わないなら `commonEvent` を embed:

```go
type fooEventFragment struct {
    commonEvent
    SomeSpecificField githubv4.String
}
```

actor / createdAt が独自フィールド (例: `submittedAt`) なら個別宣言:

```go
type fooEventFragment struct {
    ID          githubv4.ID
    Author      actorFragment
    SubmittedAt githubv4.DateTime
}
```

### 3.2 Query 追加 (`internal/timeline/query.go`)

From sushichan044/gh-timeline, MIT.

More from sushichan044/gh-timeline