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 skill，并希望让现有代码与之保持一致

此技能是 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> — 使用 ripgrep 检查每个 .ts/.tsx/.js/.jsx 文件中的 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 中配置的等效命令）。如果有任何检查失败，git restore 会还原 codemod 修改的所有文件。

按顺序运行以上全部四步。如果用户只想扫描，则在第 2 步后停止。

五种 Codemod

ID	检测内容	重写为
throttle-ms	withOptions({ throttleMs: N }) 或 setX(v, { throttleMs: N })	withOptions({ limitUrlUpdates: throttle(N) })，并将 throttle 添加到 nuqs 导入中
manual-debounce	围绕 useQueryState setter 的 useState 镜像状态 + useEffect + setTimeout 防抖	withOptions({ limitUrlUpdates: debounce(N) })，并将 debounce 添加到 nuqs 导入中；删除镜像状态和 effect
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'（未带版本号的导入历史上指向的别名）
parser-builder-type	来自 nuqs 的 ParserBuilder<T> 类型引用	SingleParserBuilder<T>

请参阅 references/workflow.md，了解各 codemod 匹配的确切 AST 形态以及刻意跳过的边缘情况。

设置

首次运行时，config.json 会填入用户的 lint/typecheck 命令和默认的 min_node_version。请参阅 config.json 中的 _setup_instructions，了解需要填写的内容。

风险与防护措施

此技能具有写入风险（会修改源文件）。防护措施：

• 如果工作区不干净，apply.sh 会中止（请先使用 git stash，或阅读 gotchas.md 后传入 --allow-dirty）
• 如果 scan.json 已超过 60 分钟，或是针对不同的 git HEAD 生成的，apply.sh 会中止——请重新运行 scan.sh
• hooks/hooks.json 中的 PreToolUse 匹配器会阻止任何绕过协调器直接调用 node scripts/transforms/*.js 的操作
• 如果 TS 或 lint 检查失败，verify.sh 会通过 git restore 自动还原被修改的文件（这些文件记录在 last-run.json 中）

相关技能

• nuqs — nuqs v2.5+ 的最佳实践参考。此技能重写旧代码；该技能定义目标模式。

注意事项

请参阅 gotchas.md，了解使用过程中发现的故障模式。