@7n/test 0.8.0 → 0.10.0

package/src/scripts/utils/docs/index.md

@@ -0,0 +1,13 @@
+---
+type: Directory Index
+title: npm/src/scripts/utils
+resource: npm/src/scripts/utils/
+---
+
+# npm/src/scripts/utils
+
+| Файл                                                | Тип       |
+| --------------------------------------------------- | --------- |
+| [lock-cache-dir.mjs](lock-cache-dir.md)             | JS Module |
+| [with-lock.mjs](with-lock.md)                       | JS Module |
+| [worktree-fingerprint.mjs](worktree-fingerprint.md) | JS Module |

package/src/scripts/utils/docs/lock-cache-dir.md

@@ -0,0 +1,32 @@
+---
+type: JS Module
+title: lock-cache-dir.mjs
+resource: npm/src/scripts/utils/lock-cache-dir.mjs
+docgen:
+  crc: 76c84505
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.97
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей модуль визначає уніфікований, спільний шлях для кешування лок-станів (`owner.json`, `result.json`) у всіх git-worktree. При наявності git-репозиторію, лок-стан розміщується у спільному каталозі `<git-common-dir>/n-cursor/<key>` (всередині `.git`), що забезпечує, щоб ресурсомісткі команди, запущені в різних worktree (наприклад, eslint), серіалізувалися та уникнули паралельного перевантаження CPU/диск на macOS. У разі відсутності git-репозиторію, використовується історичний fallback у per-checkout `node_modules/.cache/n-cursor/<key>`.
+
+## Поведінка
+
+Поведінка:
+
+1. Викликається функція resolveLockCacheDir з ключем локу.
+2. Функція з'ясовує робочу директорію.
+3. Виконується команда `git rev-parse --git-common-dir` у робочій директорії для визначення спільної директорії git-репозиторію.
+4. Якщо команда Git не спрацювала або не повернула шлях, функція повертає шлях до локального кешу (`node_modules/.cache/n-cursor/<key>`) у поточній робочій директорії.
+5. Якщо спірна директорія була знайдена, функція обчислює та повертає абсолютний шлях до кешу (`<git-common-dir>/n-cursor/<key>`) у корені репозиторію.
+6. Функція не модифікує файлову систему; вона лише обчислює шлях для кешування лок-станів (таких як `owner.json` та `result.json`) для забезпечення серіалізації важких команд між різними git-worktree.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.
+- Свідомо пропускає шляхи: `.git`, `node_modules`.

package/src/scripts/utils/docs/with-lock.md

@@ -0,0 +1,38 @@
+---
+type: JS Module
+title: with-lock.mjs
+resource: npm/src/scripts/utils/with-lock.mjs
+docgen:
+  crc: f6c6a780
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл реалізує механізм гарантування атомарності та уникнення повторного виконання (dedup) для ресурсомістких операцій. Він забезпечує, щоб важкі команди виконувалися лише один раз протягом встановленого терміну дії, якщо їхній результат збережений. Система спирається на конфігурації `owner.json` та `result.json` для керування станом блокування та кешу.
+
+Цей файл забезпечує атомарне виконання складних команд. Це досягається за допомогою механізму блокування, що базується на створенні директорії (`mkdirSync-based lock`), та валідації живості PID. Для уникнення повторних викликів використовується deduplication на основі хешу SHA256 з обмеженим часом життя (TTL), що дозволяє використовувати кешований результат.
+
+## Поведінка
+
+shouldDedup перевіряє, чи можна повторно використати збережений результат, порівнюючи його з поточним відбитком робочого дерева та перевіряючи термін дії кешу.
+
+withLock виконує важку команду, гарантуючи її атомарність за допомогою механізму блокування. Перед виконанням він перевіряє кеш, а після завершення зберігає результат для майбутньої дедуплікації.
+
+## Публічний API
+
+Зрозумів. Я буду діяти як технічний письменник, створюючи лаконічну поведінкову документацію на українській мові у чистому Markdown. Я дотримуватимуся всіх обмежень: лише "ЩО" і "НАВІЩО", без вступів/висновків, без ```-блоків, без сигнатур/типів/параметрів/stdlib-модулів/regex/приватних імен.
+
+Я інтегрую прив'язку до конфігів `owner.json` та `result.json`.
+
+Для наданого списку я перетворю його на стислі маркери у форматі «назва — що робить», використовуючи власні слова, без типів і сигнатур, та використовуючи надані назви:
+
+- shouldDedup — Визначає, чи можна ігнорувати повторне виконання, якщо результат вже є у кешованому `result.json`.
+- withLock — Гарантує послідовне виконання ресурсомісткої операції за допомогою атомарної блокировки, а також усуває дублікати за унікальним ідентифікатором (fingerprint).
+
+## Гарантії поведінки
+
+- Кешує результати в межах одного прогону.

package/src/scripts/utils/docs/worktree-fingerprint.md

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: worktree-fingerprint.mjs
+resource: npm/src/scripts/utils/worktree-fingerprint.mjs
+docgen:
+  crc: df297382
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Робота цього файлу полягає у генерації унікального цифрового відбитка поточного стану робочого дерева проєкту за допомогою функції `worktreeFingerprint`. Він збирає інформацію про стан коміту Git та контент файлів, що ще не додані до відстеження. Це дозволяє однозначно ідентифікувати консистенцію робочої копії репозиторію.
+
+## Поведінка
+
+1. Обчислення консистенції робочого дерева.
+2. Зчитування хешу поточного коміту Git.
+3. Зчитування тексту відмінностей між комітом і робочим деревом.
+4. Зчитування списку невідстежуваних файлів Git.
+5. Для кожного невідстежуваного файлу обчислюється його хеш.
+6. Утворюється відсортований список пар, що містять назву файлу та його хеш.
+7. Усі зібрані дані (хеш коміту, текст відмінностей, відсортовані пари невідстежуваних файлів) конкатенуються в один текстовий блок.
+8. Від цього текстового блоку обчислюється SHA256 хеш.
+9. Якщо будь-яка частина процесу не може бути виконана (наприклад, поточний каталог не є Git-репозиторієм), функція повертає null.
+
+## Публічний API
+
+worktreeFingerprint — визначає унікальний відбиток поточного стану git-робочого дерева.
+
+## Гарантії поведінки
+
+- (специфічних машинно-виведених гарантій немає)

package/src/scripts/utils/lock-cache-dir.mjs

@@ -9,7 +9,7 @@
  *
  * `git rev-parse --git-common-dir` повертає той самий `.git` головного репо з
  * будь-якого worktree, тож стан кладемо під `<git-common-dir>/n-cursor/<key>`
- * (всередині `.git` — спільне, ніколи не трекається, переживає `bun i`).
+ * (всередині `.git` — спільне, ніколи не відстежується, переживає `bun i`).
  * Поза git-репо (git недоступний / каталог не репо) — fallback на per-checkout
  * `node_modules/.cache/n-cursor/<key>`, як було історично.
  */

package/src/scripts/utils/with-lock.mjs

@@ -50,8 +50,7 @@ function makeRelease(lockDir) {
 export function shouldDedup(result, fingerprint, ttl) {
   if (result.exitCode !== 0) return false
   if (fingerprint === null || result.fingerprint !== fingerprint) return false
-  if (Date.now() - result.finishedAt >= ttl) return false
-  return true
+  return Date.now() - result.finishedAt < ttl
 }
 
 /**
@@ -126,7 +125,7 @@ export async function withLock(key, runFn, opts = {}) {
     /* result.json не існує або пошкоджений */
   }
 
-  // Після release лок ре-рейзиться той самий сигнал: `once` вже зняв обробник,
+  // Після release блокування повторно надсилає той самий сигнал: `once` вже зняв обробник,
   // тож процес завершується дефолтною дією з коректним кодом (130/143)
   const onSignal = signal => {
     release()