@nitra/cursor 3.27.0 → 3.29.0

package/skills/taze/js/diff.mjs

@@ -1,18 +1,4 @@
-/**
- * `n-cursor taze diff` — read-only детермінований diff версій залежностей між
- * `package.json` і його бекапом `package.json.taze-bak` (root + усі воркспейси
- * монорепо), із класифікацією кожної зміни за semver.
- *
- * Мотивація: скіл `n-taze` раніше казав LLM-агенту вручну порівнювати backup із
- * новим `package.json` по всіх воркспейсах і вирішувати, де «змінилась перша
- * значуща цифра semver» (major). Це детермінований JSON-diff + semver-логіка —
- * скрипт робить це за мілісекунди й без помилок, а агент отримує готовий список
- * major-оновлень для справді когнітивної роботи (читання CHANGELOG, рефакторинг).
- *
- * «Breaking» (major) рахуємо за caret-семантикою — змінилась найлівіша ненульова
- * компонента: `1.x→2.x`, `0.4.x→0.5.x`, `0.0.3→0.0.4`. Minor/patch вважаємо
- * сумісними.
- */
+/** @see ./docs/diff.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'

package/skills/taze/js/docs/diff.md

@@ -0,0 +1,33 @@
+# diff.mjs
+
+## Огляд
+
+Файл `n-cursor taze diff` порівнює поточну версію `package.json` з її резервною копією (`package.json.taze-bak`) для виявлення змін залежностей. Він класифікує ці зміни за семантикою версій (major, minor, patch) та надає список оновлень, які потребують уваги. Це автоматизує процес, який раніше виконувався вручну, забезпечуючи швидкий та точний аналіз змін у залежностях монорепо.
+
+## Поведінка
+
+`parseVersion` парсує версійний specifier, ігноруючи range-префікси, і повертає об'єкт з major, minor та patch компонентами, або null, якщо spec не є semver.
+`isBreaking` визначає, чи є перехід від старої до нової версії "breaking" за caret-семантикою.
+`diffPackageJson` порівнює два об'єкти `package.json`, виявляє major-оновлення та підраховує minor/patch зміни для залежностей.
+`collectTazeDiff` збирає diff по всіх воркспейсах монорепо, порівнюючи `package.json` з бекапом, та повертає список major-оновлень, кількість minor/patch змін, загальну кількість порівняних воркспейсів та кількість воркспейсів, які були порівняні.
+`runTazeCli` запускає CLI `n-cursor taze diff`, збирає diff по воркспейсах, та виводить результат у форматі JSON.
+
+## Публічний API
+
+- parseVersion — Розбирає semver-версію з специфікатора.
+- isBreaking — Визначає, чи є перехід breaking за caret-семантикою.
+- diffPackageJson — Порівнює два package.json-об'єкти та визначає зміни залежностей.
+- collectTazeDiff — Збирає diff для монорепо, порівнюючи package.json з резервною копією.
+- runTazeCli — Запускає CLI для виведення компактного JSON з інформацією про major-оновлення та кількість minor/patch.
+
+## Гарантії поведінки
+
+- Скрипт повертає `true`, якщо всі воркспейси монорепо успішно порівняні.
+- Скрипт повертає `false` та `null`, якщо виникла будь-яка помилка під час порівняння.
+- Результат порівняння завжди є `null`, якщо `package.json` або `package.json.taze-bak` не є валідним JSON.
+- Результат порівняння містить список major-оновлень, визначених за caret-семантикою.
+- Minor та patch оновлення не включаються в результат.
+- Результат завжди детермінований, тобто при однаковому вході скрипт завжди повертає однаковий результат.
+- Скрипт не використовує кешування.
+- Скрипт не кидає винятків.
+- Скрипт перехоплює помилки та повертає `false` та `null`.