pierre-guard

Pierre 統合ガード

Plannotator のコードレビュー UI は、Shadow DOM を使用するオープンソースの差分レンダラーである @pierre/diffs をラップしています。統合処理は単一のファイルに集約されていますが、ドキュメント化されていない内部仕様（Shadow DOM のセレクター、CSS 変数名、グリッドレイアウトの前提）に依存しています。このスキルは、変更によってその契約が壊れないことを確認するためのものです。

信頼できる情報源

• 上流リポジトリ：https://github.com/pierrecomputer/pierre/tree/main/packages/diffs
• ローカルの型定義：node_modules/@pierre/diffs/dist/（.d.ts ファイル）
• 統合箇所：packages/review-editor/components/DiffViewer.tsx
• 現在のバージョン：固定されているバージョンは packages/review-editor/package.json で確認してください

API の形状を記憶に頼らず、必ず上流リポジトリまたはローカルの .d.ts ファイルで確認してください。

インポートするもの

import { FileDiff } from '@pierre/diffs/react';
import { getSingularPatch, processFile } from '@pierre/diffs';

インポートはこの3つだけです。Pierre に触れるファイルは DiffViewer.tsx だけです。

ガード対象の API サーフェス

1. コンポーネントの Props（FileDiff）

現在の prop 型は node_modules/@pierre/diffs/dist/react/index.d.ts または上流ソースで確認してください。使用している props は次のとおりです。

Prop	型	備考
fileDiff	FileDiffMetadata	getSingularPatch() または processFile() から取得
options	FileDiffOptions<T>	下記のオプション表を参照
lineAnnotations	DiffLineAnnotation<T>[]	{ side, lineNumber, metadata }
selectedLines	SelectedLineRange | null	{ start, end, side }
renderAnnotation	(ann) => ReactNode	インライン注釈のカスタムレンダラー
renderHoverUtility	(getHoveredLine) => ReactNode	ホバー時の + ボタン（上流では非推奨のため、削除に注意してください）

2. Options オブジェクト

オプション	渡す値	リスク
themeType	'dark' | 'light'	低 — 標準の列挙型
unsafeCSS	CSS 文字列	高 — 内部セレクターを対象とします
diffStyle	'split' | 'unified'	低 — 標準の列挙型
diffIndicators	'bars'	低
hunkSeparators	'line-info'	低
enableLineSelection	true	低
enableHoverUtility	true	中 — 非推奨の prop
onLineSelectionEnd	コールバック	中 — シグネチャが変更される可能性があります

3. Shadow DOM セレクター（unsafeCSS 経由）

これらは CSS ルールを適用するセレクターです。Pierre の Shadow DOM 内にある data-* 属性を対象としています。Pierre がこれらのいずれかを変更または削除すると、スタイル設定は気づかないうちに壊れます。

現在使用中：

• :host — Shadow Root
• [data-diff] — 差分のルートコンテナー
• [data-file] — ファイルラッパー
• [data-diffs-header] — ヘッダーバー
• [data-error-wrapper] — エラー表示
• [data-virtualizer-buffer] — 仮想スクロールバッファー
• [data-file-info] — ファイルメタデータ行
• [data-column-number] — 行番号ガター
• [data-diffs-header] [data-title] — タイトル（非表示にします）
• [data-diff-type='split'] — 分割レイアウトモード
• [data-overflow='scroll'] / [data-overflow='wrap'] — オーバーフローモード

4. 上書きする CSS 変数

Pierre のテーマ設定のため、次の --diffs-* 変数を上書きします。

• --diffs-bg、--diffs-fg — 基本色
• --diffs-dark-bg、--diffs-light-bg — テーマ別の背景色
• --diffs-dark、--diffs-light — テーマ別の前景色

5. 注入する CSS 変数（カスタム）

Shadow DOM の外側にあるラッパー div にこれらを設定し、CSS カスタムプロパティの継承に依存します。

• --split-left、--split-right — 分割ペインのグリッド比率を制御

unsafeCSS によるグリッドの上書きでは、次のようにこれらを参照します：grid-template-columns: var(--split-left, 1fr) var(--split-right, 1fr)。1fr のフォールバックにより、変数が設定されていない場合も安全なレイアウトが維持されます。

6. グリッドレイアウトの前提

Pierre の分割ビューでは、grid-template-columns: 1fr 1fr を使った CSS Grid を使用しています。リサイズ可能な分割ペインにするため、これをオーバーライドしています。Pierre がレイアウトエンジンを変更した場合（例：flexbox や別のグリッド構造への変更）、このオーバーライドは機能しなくなります。

確認方法： アップストリームのソースで、差分コンポーネントのスタイル内にある grid-template-columns を検索してください。

検証チェックリスト

Pierre の統合に関わる変更をレビューする際は、以下を確認してください。

Props と型

• 現在の .d.ts ファイルを読み、prop 名と型に変更がないことを確認する
• renderHoverUtility が引き続きサポートされているか確認する（非推奨のため、削除される可能性があります）
• DiffLineAnnotation が引き続き side: 'deletions' | 'additions' を使用していることを確認する（'old' | 'new' ではありません）
• SelectedLineRange の形状を確認する：{ start, end, side? }

Shadow DOM セレクター

• unsafeCSS で対象としている各 data-* 属性をアップストリームのソースで検索する
• パッケージのバージョンをアップグレードする場合は、属性名変更の有無を確認するため、旧版と新版の CSS／HTML 出力を比較する
• split ビューと unified ビューの両方をテストする（セレクターはレイアウトに依存します）

CSS 変数

• --diffs-bg、--diffs-fg、およびオーバーライドしているその他の変数をアップストリームで検索する
• 変数名が変更または削除されていないことを確認する
• !important が引き続き必要か確認する（Pierre が詳細度を変更している可能性があります）

テーマへの準拠

• 新しい UI 要素では、bg-blue-500 のようなハードコードされた色ではなく、テーマトークン（bg-border、bg-primary など）を使用する
• packages/ui/components/ResizeHandle.tsx にある既存の ResizeHandle コンポーネントが視覚的な規約を示しています。これに合わせてください

ビルドと実行時

• bun run dev:review を実行し、差分が分割モードと統合モードの両方で表示されることを確認する
• ブラウザーのコンソールで Pierre の警告（例：parseLineType: Invalid firstChar）を確認する
• 追加のみ、削除のみのファイルでテストする（Pierre はこれらのファイルでは分割グリッドをレンダリングしません）
• UI コードを変更する場合は、ビルド順序を忘れずに確認する：bun run --cwd apps/review build && bun run build:hook

@pierre/diffs のアップグレード時

1. https://github.com/pierrecomputer/pierre でアップストリームの変更履歴／コミット履歴を確認する
2. 旧バージョンと新バージョンの .d.ts ファイルを比較する：

   # Before upgrading, snapshot current types
   cp -r node_modules/@pierre/diffs/dist /tmp/pierre-old
   # After upgrading
   diff -r /tmp/pierre-old node_modules/@pierre/diffs/dist
   

3. 新バージョンで名前が変更または削除された data 属性を検索する
4. 上記の検証チェックリスト全体を実施する
5. リサイズ可能な分割ペインをテストする（グリッドレイアウトの内部実装に依存しています）