nuqs-codemod-runner

nuqs Codemod Runner

コードベースを v2.5 より前の nuqs のパターンから、現在の v2.5～v2.8 のイディオムに移行します。このスキルはデフォルトで読み取り専用です。明示的な確認ステップなしにファイルを変更することはなく、Git の作業ツリーに未コミットの変更がある場合は実行を拒否します。

適用するタイミング

次の場合にこのスキルを使用します。

• nuqs をすでに使用しているプロジェクトで、ユーザーが「nuqs をアップグレード」または「nuqs 2.x に移行」と依頼したとき
• レビュー中に、5 つのレガシーパターンのいずれかを見つけたとき（以下の codemod テーブルを参照）
• 差分に、package.json の nuqs のバージョンを <2.5 から >=2.5 に変更する内容が含まれているとき
• ユーザーがnuqs スキルをインストールまたは更新したばかりで、既存のコードをその内容に合わせたいとき

このスキルは、skills/.curated/nuqs/ の自動化用コンパニオンです。あちらのスキルでは正しいパターンを解説し、このスキルではレガシーコードを書き換えて一致させます。

ワークフローの概要

┌──────────┐    ┌────────────┐    ┌──────────────────┐    ┌───────────┐    ┌────────────┐
│  scan.sh │──▶ │ scan.json  │──▶ │   report.sh      │──▶ │ apply.sh  │──▶ │ verify.sh  │
└──────────┘    └────────────┘    │ (dry-run table)  │    │ (codemods)│    │ (tsc+lint) │
                                  └──────────────────┘    └───────────┘    └────────────┘
                                          │                     ▲                │
                                          ▼                     │                ▼
                                  user reviews ────────────  confirms       on fail: revert

1. scripts/scan.sh <repo-root> — すべての .ts/.tsx/.js/.jsx ファイルを ripgrep で検索して 5 つのレガシーパターンを検出し、{path, line, matchedPattern, snippet, suggestion} を含む scan.json を出力します。
2. scripts/report.sh — scan.json を codemod ごとにまとめた Markdown テーブルとして表示し、ファイルパスと変更前／変更後のペアを示します。この出力をそのままユーザーに提示し、続行する前に明示的な確認を求めてください。
3. scripts/apply.sh [--filter <codemod-id>] — scripts/transforms/ の jscodeshift 変換を実行します。現在の git HEAD に対する新しい scan.json があり、作業ツリーがクリーンな場合にのみ実行されます（--allow-dirty で上書きできます）。
4. scripts/verify.sh — tsc --noEmit と npm run lint を実行します（または config.json に設定された同等のコマンドを実行します）。失敗した場合は、codemod が変更したすべてのファイルを git restore で元に戻します。

4 つの手順を順番に実行します。ユーザーがスキャンのみを希望する場合は、手順 2 で終了します。

5 つの Codemod

ID	検出対象	書き換え先
throttle-ms	withOptions({ throttleMs: N }) または setX(v, { throttleMs: N })	withOptions({ limitUrlUpdates: throttle(N) }) に書き換え、nuqs の import に throttle を追加
manual-debounce	useQueryState セッターの周囲にある、useState のミラー、useEffect、setTimeout によるデバウンス	withOptions({ limitUrlUpdates: debounce(N) }) に書き換え、nuqs の import に debounce を追加し、ミラー状態とエフェクトを削除
unchecked-json-cast	parseAsJson<T>()（バリデーターなし）または parseAsJson((v) => v as T)	// TODO: validate の型ガードのスタブを挿入します。package.json で Zod が検出された場合は、parseAsJson(SchemaName.parse) 形式にします
react-router-unversioned	from 'nuqs/adapters/react-router'	from 'nuqs/adapters/react-router/v6'（バージョン指定なしの import が従来指していたエイリアス）
parser-builder-type	nuqs の ParserBuilder<T> 型への参照	SingleParserBuilder<T>

各 codemod が一致する AST の正確な形式と、意図的にスキップするエッジケースについては、references/workflow.md を参照してください。

セットアップ

初回実行時に、ユーザーの lint／型チェック用コマンドとデフォルトの min_node_version が config.json に設定されます。記入する内容については、config.json の _setup_instructions を参照してください。

リスクと保護策

このスキルには書き込みリスクがあります（ソースファイルを変更します）。保護策は次のとおりです。

• apply.sh は作業ツリーに未コミットの変更がある場合、中止します（先に git stash を実行するか、gotchas.md を読んでから --allow-dirty を指定してください）
• apply.sh は、scan.json が 60 分より古い場合、または異なる git HEAD に対して生成された場合、中止します。scan.sh を再実行してください
• hooks/hooks.json の PreToolUse マッチャーが、オーケストレーターを迂回する node scripts/transforms/*.js の直接実行をブロックします
• TS または lint の検証が失敗すると、verify.sh は last-run.json に記録された変更対象ファイルに対して git restore を実行し、自動的に元に戻します

関連スキル

• nuqs — nuqs v2.5 以降のベストプラクティスを参照するスキルです。このスキルはレガシーコードを書き換え、あちらのスキルは移行先を定義します。

注意点

使用中に判明した失敗の原因については、gotchas.md を参照してください。