nullable-new-params

Null を許容する新しいパラメーター

新しいパラメーターまたは型メンバーをオプションとして追加する変更には、このスキルを使用してください。Remotion の内部コードでは、新しい入力は必須かつ null 許容にし、すべての呼び出し元が明示的に選択するようにします。

ルール

• 内部コントラクトでは、name?: T ではなく name: T | null と記述します。
• 値がない場合、呼び出し元は明示的に null を渡す必要があります。
• null を「値がない」ことを示す値として使う場合、実装では value === null または value !== null によるチェックを優先します。
• 周囲のローカルコントラクトですでに undefined を標準としている場合を除き、新しい内部 API で undefined を「値がない」ことを示す値として使わないでください。
• frozenFrame?: number | null のような冗長な型もアンチパターンです。frozenFrame: number | null としてください。

公開 API は例外です。変更後のシグネチャ、props 型、またはオプションオブジェクトがパッケージの公開エントリーポイントからエクスポートされているか、packages/docs/docs に記載されている場合、新しいフィールドまたは引数を必須にすると破壊的変更になります。オプションのままにするか、後方互換性のあるオーバーロードまたはオプションの指定方法を追加し、必要に応じてドキュメントを更新したり、デフォルト値を設定したりしてください。

ワークフロー

1. diff を確認し、新しく追加されたオプションのメンバーやパラメーターを探します。

bun .agents/skills/nullable-new-params/scripts/find-new-optional-params.ts

便利なバリエーション：

bun .agents/skills/nullable-new-params/scripts/find-new-optional-params.ts origin/main...HEAD
bun .agents/skills/nullable-new-params/scripts/find-new-optional-params.ts --cached

2. 候補ごとに公開 API かどうかを判定します。

   • 公開：パッケージのエントリーポイントからエクスポートされている、パッケージの exports に含まれている、または packages/docs/docs に記載されているもの。
   • 内部：ローカルヘルパー、内部コンポーネントの props、ファイルをまたぐモノレポ内ヘルパー、テストユーティリティ、内部コンテキストデータ、パッケージのエントリーポイントから公開されていない型。
   • 判断に迷う場合は、API の形を変更する前にパッケージのエントリーポイントとドキュメントを grep で確認してください。

3. 内部の候補については、型をオプションから必須かつ null 許容に変更します。

type Before = {
  readonly frame?: number;
};

type After = {
  readonly frame: number | null;
};

関数パラメーターの場合：

const before = (frame?: number) => {};
const after = (frame: number | null) => {};

4. すべての呼び出し元やオブジェクトリテラルを更新し、値を明示的に渡します。

   • 値がない場合は field: null を使用します。
   • 周囲のコードから undefined が入る可能性が残っている場合に限り、既存の値を field: maybeValue ?? null で保持します。
   • 分割代入のデフォルト値を使って、必須の選択を隠さないでください。

5. 実装ロジックを更新します。

   • 0、''、false が有効な値の場合、truthy チェックを置き換えます。
   • null を許容する数値、文字列、真偽値では、value ではなく value !== null を優先します。
   • 既存のテストやフィクスチャを更新する場合は、明示的な指定を維持してください。新しいフィールドを避けるためだけに、大きなフィクスチャを Partial<T> にしないでください。

6. 公開候補については、後方互換性を維持します。

   • 公開型では新しいフィールドをオプションのままにします。
   • 境界で、通常は const internal = publicValue ?? null を使って、内部向けの具体的な値を解決します。
   • 下流の内部型は必須かつ null 許容のままにします。

7. 検証します。

   • 意図的な公開 API の例外だけが残るまで、スキャナーを再度実行します。
   • 変更したパッケージに対して、対象を絞ったテストまたはパッケージビルドを実行します。たとえば、bunx turbo run make --filter='<package-name>' を実行します。
   • ドキュメントを変更した場合は、writing-docs スキルに従ってください。

レビューチェックリスト

• 新しく追加された内部の ?: メンバーや param?: パラメーターが残っていない。
• すべての内部の呼び出し元が、実際の値または null を渡している。
• 公開 API の後方互換性が維持されている。
• null のチェックで、有効な falsy 値が「値なし」と扱われていない。
• 動作が値なしの場合に依存する場合は、既存のチェックまたは手動検証で明示的な null の経路を確認している。