Crowi Deps

Crowi Deps (security 依存の本質的対応)

GitHub Dependabot の open security alert を 根本原因で潰す skill。crowi-orchestrate の D 系統が「新規 advisory の検知 + 報告」だけを担うのに対し、この skill は 実際に 直す(version bump / parent bump / override / major 待ちの報告)+ 検証 + commit まで。

単発起動の想定: 「最近 dependency 見てないな」というとき /crowi-deps を打つ。 crowi-orchestrate の D 系統からも fix の本体としてこの skill を参照する。

鉄則

• bump を最優先・override は最終手段。direct dep は宣言版を上げる。transitive は 親を上げて patched 版を引けるなら親を bump(= version up)。親が上げられない genuinely transitive のときだけ pnpm.overrides で patched に固定する(override は ad-hoc ではなく「直接 bump 経路が無い transitive」専用の正規手段。理由を残す)。
• 場当たり的でなく本質的に。advisory / changelog を読み、なぜその版で直るかを 確認してから上げる。
• major upgrade を要するものは強行しない。判断系なので報告に残すだけにして、 着手が決まったら .feature-state/specs/ に spec を切る(退避先のファイルは無い — 残件は pnpm outdated と Dependabot がいつでも再導出する)。high/critical が major 待ちで滞留するなら ping。
• push しない(commit まで。push は user 指示待ち)。
• 検証して通してから commit(lint errors=0 / type-check / 影響パッケージの test)。

手順

0. 既存 override の棚卸し(bump で不要になった override を剥がす)

pnpm.overrides は追加され続ける一方で、後から親パッケージ自身が自然に patched 版を 引くようになっても自動では外れない(override が残り続けると、なぜ入れたか分からない エントリが積み重なる)。新規 alert の処理を始める前に、root package.json の pnpm.overrides に列挙された各エントリ("<pkg>@<range>": "<version>")が今も 必要か、1 件ずつ機械的に確認する:

判定基準は 1 つだけ: そのエントリを外したとき、キーの範囲 (<pkg>@<range> の <range>) を満たす版が実際に解決されるか。キーの範囲は advisory の脆弱範囲そのものなので、この問いがそのまま「この override はまだ効いているか」と一致する。

# 各エントリについて 1 件ずつ:
# 1. そのエントリだけ一時的に削除(他のエントリは触らない)
# 2. pnpm install
# 3. lockfile の解決版を読み、キーの範囲を満たす版が現れたか semver で判定
#    — 現れた   → STILL-NEEDED (この override が押さえている。元に戻す)
#    — 現れない → REMOVABLE 候補(ただし下記の限界を読むこと)

「pin 以上か」で判定しない。 major スコープの override (brace-expansion@2 など) は自分の major しか支配しないので、pin との単純な大小比較は無関係な major を巻き込んで誤判定する。必ずキーの範囲に対する semver 判定にする。

実装上の落とし穴 3 つ(いずれも実際に踏んだ)

1. lockfile の overrides: セクションを解決版として拾わない。 brace-expansion@1: 1.1.18 のような行も <pkg>@<x>: の形にマッチするため、1 をバージョンとして誤読する。packages: セクション以降だけを対象にする。
2. pnpm why の出力をテキストで解析しない。 先頭行が <pkg>@<version> で、階層は罫線で表現される。書式に依存した正規表現は壊れやすい。lockfile を直接読むほうが安定する。
3. pnpm のキーには peer 情報が付く。 @hono/node-server@2.0.11(hono@4.13.0) のような形になるので、(...) を落としてから semver に渡す。

REMOVABLE の限界(機械的に削除しない)

REMOVABLE が示すのは「脆弱範囲を要求する利用者が居ない」ことだけで、「override 無しでも patched 版に解決され続ける」ことは保証しない。lockfile が既に patched 版を記録していると、override を外しても慣性でその版が残るためである。

したがって 同じ実行の中で自分が追加した override は、必ず REMOVABLE に見える。それは「不要」ではなく「その override が版を動かした当事者」である証拠なので、消してはならない。判定を鵜呑みにせず、その override がいつ・なぜ入ったかと突き合わせる:

• 外してよい: 後から別経路で解決版が上がって用済みになったもの(例: catalog の bump で typescript-eslint が override 無しでも patched に到達した)

• 外してはいけない: 今まさにその override が版を押さえているもの(pnpm update -r で動かなかった transitive がこれに当たる)

• 1 エントリずつ確認する(まとめて全部外して確認すると、どれが不要でどれが必須か 切り分けられない)。

• 不要と確定したものは削除し、commit メッセージに「override <pkg> を削除(理由)」と 1 行残す。削除後は lint / type-check / 影響パッケージの test まで通す (override の削除は依存ツリーを動かすため、追加と同じ検証が要る)。

• 全件確認しても不要なものが無ければ「棚卸し: 変更なし(全 override 継続要)」と 報告するだけでよい(commit 不要)。

• この棚卸しは新規 alert が 0 件のときも独立して価値がある(/crowi-deps を alert 無しで単発起動しても棚卸しだけは走らせてよい)。

• 判定が信用できないときは 1 件も削除しない。誤った根拠で override を外すと脆弱性を 静かに戻すので、「cruft が残る」より「誤って外す」ほうが悪い。

1. 取得

gh api repos/crowi/crowi/dependabot/alerts --paginate -X GET -f state=open \
  --jq '.[] | "\(.number)\t\(.security_advisory.severity)\t\(.dependency.package.name)\t\(.dependency.scope)\tpatched:\(.security_vulnerability.first_patched_version.identifier // "none")"' \
  | sort -t$'\t' -k3,3 -k2,2

gh が無い / 未認証なら skip(「gh 未認証で skip」とだけ報告)。

2. 分類(package ごと)

• direct か transitive か: grep -rlE '"<pkg>"' packages/*/package.json apps/*/package.json package.json(見つかれば direct、その package と dep/devDep の別も見る)。
• transitive の親 + 引いている版: pnpm why -r <pkg>。
• patched 版: alert の first_patched_version。
• severity / scope(runtime / development)。

3. 対応の選択(本質的な順)

override の書き方: root package.json の pnpm.overrides(または pnpm-workspace.yaml)に、既存パターン(例 "postcss@<8.5.13": "8.5.15")へ合わせ per-major で書く。素の "undici": ... は別 major の利用者を壊すので避け、 "undici@6": "^6.27.0" / "undici@7": "^7.28.0" のように major ごとに固定する。

4. 検証

pnpm install(lockfile 更新)後:

• pnpm lint(errors=0 必須)
• 影響パッケージの pnpm --filter <pkg> type-check
• 影響パッケージに test があれば その test(pnpm --filter <pkg> test、api は flaky 回避で単独実行)。無ければ build + type-check で API 互換を確認し、可能なら最小 test を足して以後の bump を守る(特に major bump は実 runtime を 1 経路通すと安心。例: nodemailer なら createTransport({ jsonTransport: true }) + sendMail)。
• 公開パッケージの bump は changeset を追加(patch/minor/major は内容で判断)。文面の主語は crowi-changesets の「依存パッケージの脆弱性対応の書き方」に従う — 依存の脆弱性を Crowi の脆弱性として書かない。

5. commit(push しない)

• fix(deps): bump <pkg> to <ver> (#<alert> / GHSA-xxxx) など。本文に「なぜこの版で 直るか」「override にした理由」を残す。
• major upgrade 待ちの未対応分は報告に 1 行残すだけにする (退避先は無い — pnpm outdated がいつでも再導出する)。
• push は user 指示待ち(commit まで)。

出力

直した alert(番号 + package + 版)/ override にしたもの(+理由)/ major 待ち(+ブロッカー) / 残件を、簡潔に表で。全件対応済み or 全件 major 待ちならその旨一言。

crowi-orchestrate との関係

• D 系統 = watcher: 新規 alert の検知 + 報告 + knownDependabotAlerts のメンテのみ。
• この skill = fixer: 実際に直す。D が「新規あり」を出したら user が /crowi-deps を 打つ(D が high/critical を見たら ping)。fix のロジックはこの skill に一本化する。