---
name: n-taze
description: >-
  Оновлення версій модулів проекту з аналізом major-змін і автоматичним
  рефакторингом несумісного коду
---

# n-taze — Оновлення версій проекту

## Мета

Оновити всі модулі проекту до останніх версій, виявити major-оновлення, перевірити сумісність змін з кодом проекту і за потреби зрефакторити несумісні місця.

## Передумови

- Чисте робоче дерево (`git status` без незакомічених змін у `package.json` / `bun.lock` / `node_modules`) — інакше різницю не відрізнити від оновлення.
- Встановлений `bun` і доступний `bunx`.
- Запуск з кореня проекту (де лежить `package.json` / `bun.lock`).

## Workflow

### 1. Зафіксувати стартовий стан

Перед оновленням зберегти список поточних версій, щоб потім обчислити, які модулі стрибнули через major:

```bash
cp package.json package.json.taze-bak
cp bun.lock bun.lock.taze-bak
```

(У monorepo — також усі `*/package.json` воркспейсів. Файли тимчасові, видалити в кінці.)

### 2. Запустити оновлення

```bash
bunx taze -w -r latest
bun install
```

- `-w` — записати нові версії у `package.json`.
- `-r` — рекурсивно по всіх воркспейсах.
- `latest` — піднімати навіть major.

### 3. Виявити major-оновлення

> **Не порівнюй `package.json` вручну.** Класифікацію semver несе CLI — детерміновано, по всіх воркспейсах.

```bash
n-cursor taze diff
```

Друкує компактний JSON: `{ "major": [{workspace, pkg, from, to}], "minorPatch": <N>, "totalChanged": <N> }`. `major` — список залежностей, у яких змінилась найлівіша ненульова компонента semver (`1.x→2.x`, `0.4.x→0.5.x`, `0.0.3→0.0.4`); саме він іде в кроки 4–6. `minorPatch` — лічба сумісних (для звіту в кроці 8).

Покриває **прямі** залежності з `package.json` (root + воркспейси). Транзитивні major-стрибки (`bun.lock`) — за потреби переглянь окремо; основний ризик breaking-змін — у прямих.

### 4. Зібрати breaking changes по кожному major-оновленню

Для кожного модуля зі списку зібрати фактичні відмінності одним з джерел (у порядку пріоритету):

1. **CHANGELOG / Releases репозиторію модуля** — найшвидше і найточніше. Адресу репозиторію взяти з `package.json` модуля у `node_modules/<name>/package.json` (поле `repository`). Дістати релізи між старою і новою версією.
2. **Git-різниця в `node_modules/<name>`** — якщо CHANGELOG відсутній або неінформативний, порівняти попередню версію (з кешу bun: `~/.bun/install/cache/<name>@<old-version>/`) з новою (`node_modules/<name>/`) через `diff -r` по `dist/` / `*.d.ts` / публічних entry-points з `exports`.
3. **Якщо немає кешованої старої версії** — встановити її окремо в тимчасову теку (`mkdir -p /tmp/taze-old && cd /tmp/taze-old && bun add <name>@<old-version>`) і порівняти.

Цікавлять: видалені/перейменовані експорти, змінені сигнатури функцій, змінені типи, змінена поведінка за замовчуванням, видалені CLI-прапорці.

### 5. Перевірити сумісність з кодом проекту

Для кожного breaking change знайти його використання в коді проекту:

```bash
rg -n "<імпорт|функція|опція>" --type ts --type js --type vue
```

Класифікувати:

- **сумісно** — проект не використовує зачеплене API → нічого не робити.
- **несумісно** — використання знайдено → перейти до п. 6.

### 6. Рефакторинг несумісних місць

Для кожного несумісного місця — застосувати міграцію згідно з changelog модуля (перейменувати імпорт, оновити сигнатуру виклику, замінити видалену опцію еквівалентом тощо). Після правок:

```bash
bun run lint
bun run typecheck   # якщо є
bun test            # якщо є
```

Якщо міграція нетривіальна або неоднозначна — **не вгадувати**, залишити TODO у коді з посиланням на CHANGELOG і винести в підсумковий звіт як ручну дію.

### 7. Прибрати тимчасові файли

```bash
rm package.json.taze-bak bun.lock.taze-bak
```

(І решту бекапів воркспейсів, якщо створювались.)

### 8. Звіт користувачу

Коротко в одному повідомленні:

- **Оновлено (minor/patch):** кількість пакетів (`minorPatch` із кроку 3), без деталей.
- **Major-оновлення:** список `<name>: <old> → <new>` з посиланням на release notes.
- **Зрефакторено автоматично:** список файлів і коротко що саме змінено.
- **Потребує ручного втручання:** список TODO з причиною (нетривіальна міграція / неоднозначність / падіння тестів).
- **Стан перевірок:** `lint` / `typecheck` / `test` — pass/fail з номером рядка, де впало.

## Примітка

- Не запускати `bun run lint` паралельно з іншими ESLint-задачами — діє правило з кореневого `CLAUDE.md`.
- Якщо проект — `npm/` пакет цього репо, після змін у `package.json` / коді треба підняти `version` і додати запис у `CHANGELOG.md` згідно з `npm/CLAUDE.md`.
- При великій кількості major-оновлень розбити PR по одному модулю на коміт — щоб `git bisect` залишався корисним.
