@nitra/cursor 3.26.0 → 3.28.0

package/scripts/lib/docs/worktree.md

@@ -0,0 +1,38 @@
+# worktree.mjs
+
+## Огляд
+
+Файл містить детерміновану логіку для обробки гілок у `worktree-tool`, забезпечуючи безпечне перетворення імен гілок та створення описових файлів для `worktree`. Він використовується для генерації структури `.worktrees/` та ідентифікації неактивних описових файлів, що необхідно для операцій з видаленням. Це ключовий компонент для забезпечення консистентності та зручності роботи з `worktree-tool` безпосередньо з файловою системою.
+
+## Поведінка
+
+sanitizeBranch: Перетворює ім’я git-гілки на безпечне ім’я каталогу/файла для `.worktrees/`, замінюючи небезпечні символи на дефіс.
+firstFreeBranch: Знаходить першу вільну назву гілки, починаючи з заданої, і повертає її.
+worktreePaths: Створює абсолютні шляхи до checkout і файла-опису для заданої гілки.
+buildDescription: Генерує markdown-вміст файла-опису `.worktrees/<name>.md` на основі наданих параметрів.
+buildDirtyNotice: Створює повідомлення про незакомічені зміни основного дерева, якщо їх є, обмежуючи кількість відображених файлів.
+findOrphanDescFiles: Знаходить `.md`-описи, які не мають відповідного зареєстрованого worktree-checkout.
+
+## Публічний API
+
+- sanitizeBranch — Перетворює ім'я гілки на безпечне ім'я для каталогу/файлу.
+- firstFreeBranch — Знаходить першу вільну назву гілки, використовуючи суфікси `base`, `base2`, `base3` тощо.
+- worktreePaths — Визначає шляхи для checkout гілки та файлу опису.
+- buildDescription — Генерує текст опису для файлу опису worktree.
+- buildDirtyNotice — Виводить повідомлення про незакомічені зміни, які не включені у worktree.
+- findOrphanDescFiles — Знаходить `.md`-описи, що не мають відповідного worktree-checkout.
+
+## Гарантії поведінки
+
+- `sanitizeBranch` повертає строку, безпечну для використання в шляхах файлової системи.
+- `sanitizeBranch` не змінює вхідну строку.
+- `worktreePaths` повертає масив з двох строк, що представляють шлях до checkout та файлу опису.
+- `worktreePaths` гарантує, що обидва шляхи є дійсними.
+- `buildDescription` повертає строку, що відповідає конвенції `worktree.mdc`.
+- `buildDescription` не змінює вхідну строку.
+- `findOrphanDescFiles` повертає масив з рядків, що представляють шляхи до файлів опису.
+- `findOrphanDescFiles` гарантує, що всі рядки в масиві є дійсними шляхами файлів.
+- Функції не викликають жодних побічних ефектів, що впливають на стан файлової системи.
+- Функції не взаємодіють з Git або будь-якими іншими системами контролю версій.
+- Результат роботи функцій не залежить від будь-яких зовнішніх факторів.
+- Функції не використовують жодного кешу.

package/scripts/utils/docs/ast-scan-utils.md

@@ -0,0 +1,50 @@
+# ast-scan-utils.mjs
+
+## Огляд
+
+Цей файл містить утиліти для AST-сканерів JavaScript та TypeScript, що використовуються для аналізу коду та виявлення потенційних проблем. Він надає інструменти для обробки AST, перетворення даних та взаємодії з різними типами вузлів, забезпечуючи основу для створення правил безпеки та аналізу коду. Ці утиліти спрощують розробку сканерів, усуваючи необхідність повторного написання boilerplate-коду.
+
+## Поведінка
+
+langFromPath: Визначає мову (js, jsx, ts, tsx) на основі розширення файлу.
+offsetToLine: Перетворює байтове зміщення в номер рядка для текстового файлу.
+normalizeSnippet: Стискає текстовий фрагмент до 180 символів, видаляючи пробіли.
+isFunctionNode: Визначає, чи є вузол AST функцією (FunctionDeclaration, FunctionExpression, ArrowFunctionExpression).
+walkAstWithAncestors: Рекурсивно обходить AST, збираючи предки вузла.
+parseProgramOrNull: Парсує файл JS/TS та повертає програму або null, якщо є помилки.
+parseProgramAndCommentsOrNull: Парсує файл JS/TS та повертає програму та список коментарів, або null, якщо є помилки.
+isJoinCall: Визначає, чи є виклик `join` у TemplateLiteral.
+templateQuasisText: Збирає текст quasis з TemplateLiteral.
+isSqlListContextTemplate: Визначає, чи є TemplateLiteral контекстом SQL-списку (IN/VALUES).
+requireCallModule: Витягує ім'я модуля з аргументу виклику `require`.
+dynamicImportModule: Витягує ім'я модуля з аргументу виклику `import`.
+
+## Публічний API
+
+- langFromPath — Визначає мову Oxc на основі розширення файлу.
+- offsetToLine — Перетворює зміщення в буфер на номер рядка.
+- normalizeSnippet — Форматує текст повідомлення про порушення, видаляючи зайві пробіли.
+- isFunctionNode — Визначає, чи є вузол у абстрактному синтаксичному дереві (AST) функцією.
+- walkAstWithAncestors — Рекурсивно обходить AST, враховуючи контекст (чи знаходиться вузол всередині функції).
+- parseProgramOrNull — Парсить файл та повертає AST, якщо успішно, або `null` у разі помилки.
+- parseProgramAndCommentsOrNull — Парсить файл та повертає об'єкт з AST та коментарями, або `null` у разі помилки.
+- isJoinCall — Визначає, чи є виклик `.join` (для динамічних списків SQL).
+- templateQuasisText — Витягує текст з `quasis` у `TemplateLiteral`, ігноруючи вирази.
+- isSqlListContextTemplate — Визначає, чи є `TemplateLiteral` контекстом SQL-списку (наприклад, `IN` або `VALUES`).
+- requireCallModule — Перевіряє, чи є виклик `require` з рядковим ім'ям.
+
+## Гарантії поведінки
+
+- `langFromPath` повертає назву мови JavaScript або TypeScript на основі розширення файлу.
+- `langFromPath` повертає `null`, якщо розширення файлу не підтримується.
+- `offsetToLine` перетворює зміщення в коді на номер рядка.
+- `offsetToLine` повертає `null`, якщо зміщення недійсне.
+- `normalizeSnippet` стискає текст сніпета.
+- `normalizeSnippet` повертає `null`, якщо не вдалося стиснути сніпет.
+- `isFunctionNode` визначає, чи є вузол AST функцією.
+- `isFunctionNode` повертає `true` якщо вузол є функцією, інакше `false`.
+- `walkAstWithAncestors` обходить AST, враховуючи предки вузлів.
+- `walkAstWithAncestors` не повертає значень.
+- `parseProgramOrNull` парсує програму та повертає її як AST або `null`, якщо парсинг не вдається.
+- `parseProgramOrNull` повертає `null`, якщо програма не може бути успішно розпарсена.
+- `parseProgramAndCommentsOrNull` парсує програму

package/scripts/utils/docs/ensure-gitignore-entries.md

@@ -0,0 +1,28 @@
+# ensure-gitignore-entries.mjs
+
+## Огляд
+
+Цей модуль відповідає за оновлення файлу `.gitignore` у корені проєкту. Він забезпечує idempotent додавання нових правил ігнорування, перевіряючи їхню наявність перед доповненням. Це необхідно для підтримки консистентності правил ігнорування в проєкті та інтеграції з інструментами тестування, такими як Stryker.
+
+## Поведінка
+
+1.  Отримує вхідні дані: каталог проєкту, список шаблонів для `.gitignore`, такий же заголовок для коментаря.
+2.  Перевіряє наявність `.gitignore` у вказаному каталозі.
+3.  Якщо `.gitignore` відсутній, створює новий файл з порожнім вмістом.
+4.  Зчитує вміст `.gitignore` (якщо він існує).
+5.  Розбиває вміст `.gitignore` на окремі рядки, видаляє пробіли на початку та в кінці кожного рядка.
+6.  Перетворює отримані рядки у набір (Set) для швидкої перевірки на наявність.
+7.  Визначає список шаблонів, яких немає у `.gitignore`.
+8.  Якщо список шаблонів, яких немає, порожній, повертає порожній масив доданих шаблонів.
+9.  Формує новий рядок для додавання у `.gitignore`. Рядок починається з заголовка, потім додає шаблони з порожнього списку, і завершується символом нового рядка.
+10. Додає сформований рядок до вмісту `.gitignore`.
+11. Записує змінений вміст `.gitignore` назад у файл.
+12. Повертає список шаблонів, які були додані до `.gitignore`.
+
+## Гарантії поведінки
+
+- Якщо файл `.gitignore` існує, то записи додаються лише якщо вони відсутні.
+- Якщо файл `.gitignore` не існує, то створюється новий файл `.gitignore` з доданими записами та header-коментарем.
+- Записи додаються лише після видалення будь-яких пробілів з початку та кінця кожного запису.
+- Якщо запис вже присутній у файлі `.gitignore`, то він не буде доданий повторно.
+- Кеш не використовується.

package/scripts/utils/docs/find-package-json-paths.md

@@ -0,0 +1,26 @@
+# find-package-json-paths.mjs
+
+## Огляд
+
+Цей файл забезпечує спільну утиліту для збору всіх файлів `package.json` у дереві проєкту, ігноруючи вказані каталоги. Він сортує знайдені шляхи пакетів за відносним розташуванням, що полегшує їх подальше використання в скриптах перевірки. Це дозволяє уникнути дублювання коду з інших інструментів перевірки та спрощує процес збору інформації про залежності.
+
+## Поведінка
+
+1.  Отримує абсолютний шлях до кореня репозиторію та список абсолютних шляхів каталогів, які потрібно ігнорувати.
+2.  Ініціалізує порожній масив для зберігання шляхів до файлів `package.json`.
+3.  Використовує обхід каталогу, починаючи з кореня репозиторію, для пошуку файлів `package.json`.
+4.  Для кожного файлу `package.json` у каталозі, перевіряє, чи він відповідає критеріям включення (не знаходиться в ігнорованих каталогах).
+5.  Якщо файл відповідає критеріям, додає його абсолютний шлях до масиву шляхів.
+6.  Після завершення обходу каталогу, сортує масив шляхів до файлів `package.json` за відносним шляхом відносно кореня репозиторію.
+7.  Повертає відсортований масив абсолютних шляхів до файлів `package.json`.
+
+## Публічний API
+
+- findAllPackageJsonPaths — Знаходить всі файли `package.json` в каталозі та підкаталогах.
+
+## Гарантії поведінки
+
+- Функція повертає масив рядків, що представляють відносні шляхи до всіх `package.json` файлів, знайдених у дереві.
+- Функція ігнорує каталоги, перелічені в аргументі `walkDir`.
+- Функція не гарантує, що `package.json` файли будуть доступні.
+- Функція не використовує кешування.

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

@@ -0,0 +1,25 @@
+# lock-cache-dir.mjs
+
+## Огляд
+
+Цей файл визначає структуру каталогу кешування блоків для git-worktree, забезпечуючи унікальний стан локу для кожного головного checkout та пов'язаних worktree. Він використовується для серіалізації запуску інструментів аналізу коду в різних worktree, запобігаючи конфліктам та забезпечуючи ефективну роботу. Створена структура кешування гарантує, що всі worktree мають доступ до одного і того ж стану локу, що необхідно для коректної серіалізації процесів аналізу.
+
+## Поведінка
+
+1.  Визначається ключ локу, що представляє конкретну задачу або конфігурацію.
+2.  Визначається робоча директорія, яка використовується для виконання операцій.
+3.  Використовується команда `git rev-parse --git-common-dir` для визначення спільного каталогу `.git`. Якщо команда успішна, отримується абсолютний шлях до каталогу `.git`. Якщо команда не вдалася, то цей шлях не визначено.
+4.  Якщо спільний каталог `.git` визначено, то обчислюється шлях до директорії стану локу, використовуючи спільний каталог, назву ключа та префікс `n-cursor`.
+5.  Якщо спільний каталог `.git` не визначено, то обчислюється шлях до директорії стану локу, використовуючи робочу директорію та префікс `node_modules/.cache/n-cursor`.
+6.  Повертається обчислений абсолютний шлях до директорії стану локу.
+
+## Гарантії поведінки
+
+- Спільний лок-стан для всіх git-worktree визначається шляхом `<git-common-dir>/n-cursor/<key>`.
+- Якщо git недоступний, використовується кеш `node_modules/.cache/n-cursor/<key>`.
+- Кеш використовується для збереження стану протягом одного прогону.
+- Стан локу (`lock/owner.json`, `result.json`) є унікальним для кожного головного checkout та всіх linked-worktree.
+- Унікальний стан локу запобігає паралельній роботі інструментів серіалізації.
+- Унікальний стан локу гарантує, що кожен worktree має власний `node_modules/.cache/`.
+- Кеш не відстежується git.
+- Кеш не впливає на стан локу.

package/scripts/utils/docs/pass.md

@@ -0,0 +1,25 @@
+# pass.mjs
+
+## Огляд
+
+Цей файл містить функцію для виведення повідомлень про успіх у консоль. Функція використовується в скриптах перевірки для інформування користувача про успішне завершення операцій. Вона забезпечує чіткий візуальний сигнал про успіх, що полегшує інтерпретацію результатів перевірки.
+
+## Поведінка
+
+1.  Викликається функція `pass`.
+2.  Функція `pass` друкує рядок у консоль.
+3.  Рядок починається з символу галочки (✅).
+4.  Після символу галочки друкується переданий текст повідомлення.
+5.  Функція не має жодного впливу на стан системи.
+6.  Функція не взаємодіє з будь-якими зовнішніми ресурсами.
+
+## Публічний API
+
+- pass: Допоміжна функція для скриптів перевірки.
+  Друкує в консоль рядок успіху з галочкою (✅).
+
+## Гарантії поведінки
+
+- Виводить у консоль рядок із символом ✅.
+- Не виконує жодних операцій.
+- Не використовує жодного кешу.

package/scripts/utils/docs/resolve-cargo-manifest.md

@@ -0,0 +1,23 @@
+# resolve-cargo-manifest.mjs
+
+## Огляд
+
+Цей файл визначає шлях до файлу Cargo.toml проєкту, незалежно від того, чи це кореневий Cargo.toml або один з підкаталогів workspace-у, особливо з урахуванням Tauri-патерну. Він служить утилітою для coverage-провайдера та test-концерну cargo_mutants_config, повертаючи `null` у разі невдачі для обробки ситуації без виключень. Це забезпечує гнучкий спосіб доступу до конфігурації проєкту Cargo.
+
+## Поведінка
+
+resolveCargoManifest: Повертає абсолютний шлях до Cargo.toml у проєкті, починаючи з кореня, або в підкаталозі `src-tauri` якщо він існує. Повертає `null`, якщо Cargo.toml не знайдено.
+resolveAllCargoManifests: Повертає масив абсолютних шляхів до всіх знайдених Cargo.toml у проєкті, пріоритет надається `src-tauri` підкаталогам, а потім загальним Cargo.toml. Повертає порожній масив, якщо жодного Cargo.toml не знайдено.
+
+## Публічний API
+
+- resolveCargoManifest: Отримує інформацію про маніфест Cargo.toml з конкретного каталогу.
+- resolveAllCargoManifests: Знаходить всі файли Cargo.toml в проєкті, починаючи з кореневого каталогу та підкаталогів workspace, повертаючи їх вміст.
+
+## Гарантії поведінки
+
+- Функція повертає `null` у разі невдачі.
+- Функція не викидає винятки.
+- Функція не використовує кешування.
+- Функція обробляє шляхи до `Cargo.toml` у каталогах `cwd/Cargo.toml` та підкаталогах workspace (`<workspace>/src-tauri/`).
+- Функція не повертає жодного значення, якщо всі шляхи до `Cargo.toml` успішно оброблені.

package/scripts/utils/docs/resolve-cmd.md

@@ -0,0 +1,29 @@
+# resolve-cmd.mjs
+
+## Огляд
+
+Цей файл надає функцію `resolveCmd` для отримання абсолютного шляху до виконуваного файлу, який відповідає заданій команді. Це дозволяє викликати зовнішні інструменти, використовуючи повний шлях до файлу, а не команду з змінної PATH. Це корисно для забезпечення чіткої та однозначної ідентифікації виконуваного файлу.
+
+## Поведінка
+
+1.  Перевіряє, чи існує команда в змінній PATH системи.
+2.  Визначає інструмент для пошуку команди: `where` на Windows та `which` на інших платформах.
+3.  Запускає визначений інструмент з командою для пошуку.
+4.  Перевіряє код повернення інструменту. Якщо код не 0 або є помилка, команда не знайдена, повертає `null`.
+5.  Якщо команда знайдена, витягує перший рядок результату.
+6.  Видаляє пробіли з рядка.
+7.  Повертає витягнутий рядок як абсолютний шлях до команди. Якщо рядок порожній, повертає `null`.
+
+## Публічний API
+
+resolveCmd — Знаходить шлях до виконуваного файлу команди в системному PATH та повертає його. Якщо команда не знайдена, повертає null.
+
+## Гарантії поведінки
+
+- Функція повертає абсолютний шлях до команди, якщо вона знайдена в змінних середовища PATH.
+- Якщо команда не знайдена в PATH, функція повертає `null`.
+- Функція не викидає винятки у разі невдачі.
+- Функція не використовує жодного кешу.
+- Функція не гарантує, що команда доступна.
+- Функція не гарантує, що команда працює.
+- Функція не гарантує, що команда безпечна для використання.

package/scripts/utils/docs/resolve-js-root.md

@@ -0,0 +1,25 @@
+# resolve-js-root.mjs
+
+## Огляд
+
+Цей файл визначає кореневий JavaScript-файл проєкту, необхідний для запуску інструментів аналізу коду. Він використовується як у великих проєктах з декількома workspace-ами, так і в окремих пакетах, забезпечуючи єдине місце для визначення кореневого розташування. Це спрощує інтеграцію з інструментами coverage та тестування.
+
+## Поведінка
+
+resolveJsRoot: повертає абсолютний шлях до першого JS-кореня проєкту.
+resolveAllJsRoots: повертає масив абсолютних шляхів до всіх JS-коренів проєкту, враховуючи glob-патерни з `workspaces` у кореневому `package.json`. Якщо JS-коренів немає, повертає абсолютний шлях до кореневого каталогу.
+
+## Публічний API
+
+- resolveJsRoot — Знаходить кореневий JS-файл проєкту.
+- resolveAllJsRoots — Знаходить всі кореневі JS-файли проєкту. Включає всі workspace-файли та їхні `package.json`, використовуючи glob-патерни. Для single-package повертає поточну директорію.
+
+## Гарантії поведінки
+
+- Повертає `true`, якщо кореневий JS-файл знайдено.
+- Повертає `false`, якщо кореневий JS-файл не знайдено.
+- Повертає `null`, якщо не вдалося визначити кореневий JS-файл.
+- Не обробляє помилки, а повертає `false` або `null`.
+- Ігнорує директорії `.git` та `node_modules`.
+- Не використовує кешування.
+- Не здійснює мережевих запитів.

package/scripts/utils/docs/test-helpers.md

@@ -0,0 +1,36 @@
+# test-helpers.mjs
+
+## Огляд
+
+Цей файл надає допоміжні функції для тестування скриптів пакета `@nitra/cursor`. Він забезпечує створення тимчасових каталогів та запис JSON-файлів у абсолютний шлях, гарантуючи ізольованість тестів та запобігаючи мутації глобального контексту процесу. Ці функції використовуються для створення безпечного середовища для тестування, особливо при використанні git-операцій та інших файлових операцій.
+
+## Поведінка
+
+withTmpDir: Створює тимчасову директорію та виконує функцію з її абсолютним шляхом, потім видаляє директорію.
+writeJson: Записує JSON-файл в абсолютний шлях, форматує його та додає символ переносу рядка.
+ensureDir: Створює вкладену директорію в заданому абсолютному шляху.
+withShellcheckStubInPath: Створює тимчасову директорію з підставленим `shellcheck` (якщо платформа Windows), додає її до `PATH`, виконує функцію, а потім відновлює оригінальний `PATH` та видаляє тимчасову директорію.
+withBinRemovedFromPath: Видаляє заданий виконуваний файл з `PATH`, виконує функцію, а потім відновлює оригінальний `PATH` та встановлює `N_CURSOR_NO_AUTO_INSTALL=1`.
+
+## Публічний API
+
+- withTmpDir — Створює тимчасову директорію та передає її шлях у `fn`, потім видаляє директорію.
+- writeJson — Записує JSON-файл з форматуванням.
+- ensureDir — Створює вкладені каталоги.
+- withShellcheckStubInPath — Створює тимчасовий каталог із `shellcheck`, додає його на `PATH` та відновлює оригінальний `PATH`.
+- withBinRemovedFromPath — Виконує `fn` з `PATH`, з якого видалено каталоги з `<bin>`.
+- N_CURSOR_NO_AUTO_INSTALL — Встановлює прапорець для запобігання автоматичному встановленню інструментів.
+
+## Гарантії поведінки
+
+- `withTmpDir` створює тимчасовий каталог і передає його абсолютний шлях у функцію `fn`.
+- `writeJson` записує об'єкт `data` у файл JSON в абсолютний шлях каталогу `dir`.
+- `ensureDir` створює каталог `dir`, якщо він не існує.
+- `withShellcheckStubInPath` встановлює stub Shellcheck у каталозі `dir`.
+- `withBinRemovedFromPath` видаляє біни з шляху `dir`.
+- Абсолютний шлях каталогу тимчасового каталогу, створеного `withTmpDir`, завжди доступний для використання.
+- Функції не кидають винятків. У разі помилки, функція завершується з помилкою.
+- Немає кешування.
+- Не використовується `process.chdir`.
+- `process.cwd` встановлюється на абсолютний шлях тимчасового каталогу.
+- Всі child-процеси отримують абсолютний шлях тимчасового каталогу через `cwd`.

package/scripts/utils/docs/walk-cache.md

@@ -0,0 +1,27 @@
+# walk-cache.mjs
+
+## Огляд
+
+Файл забезпечує спільний кеш результатів обходу файлової системи для всіх операцій перевірки. Він зберігає список файлів, що відповідають заданим шаблонам, щоб уникнути повторних обходів. Це підвищує ефективність процесу перевірки, особливо при великій кількості файлів та шаблонів.
+
+## Поведінка
+
+getOrCreateWalkCache: Створює або повертає кеш.
+resetWalkCache: Скидає кеш.
+
+## Публічний API
+
+- getOrCreateWalkCache — Створює або повертає cache, ініціалізує його при першому використанні.
+- resetWalkCache — Очищає cache.
+
+## Гарантії поведінки
+
+- Кеш існує лише в межах одного процесу.
+- Кеш скидається при виклику `resetWalkCache`.
+- Кеш зберігає список файлів, отриманий в результаті прогону.
+- Значення кешу – `Promise<string[]>`.
+- Кеш використовується для обробки glob/regex дескрипторів.
+- Кеш не використовується для взаємодії з мережею.
+- Кеш зберігає дані лише протягом одного прогону.
+- Кеш не гарантує наявності файлів, що відповідають дескрипторам.
+- Кеш не гарантує порядку файлів у списку.

package/scripts/utils/docs/walkDir.md

@@ -0,0 +1,32 @@
+# walkDir.mjs
+
+## Огляд
+
+Файл `n-cursor.js` забезпечує рекурсивний обхід каталогів для скриптів перевірки, дозволяючи виконувати callback-функцію для кожного звичайного файлу. Він обходить дерево каталогів від заданого кореня, ігноруючи певні директорії (наприклад, `.git`, `node_modules`) та шляхи, вказані в `ignorePaths`. Це дозволяє автоматизувати процес аналізу конфігураційних файлів та інших ресурсів у проєкті.
+
+## Поведінка
+
+1.  Починається з заданого кореневого каталогу.
+2.  Для кожного підкаталогу в кореневому каталозі:
+    2.1. Перевіряє, чи є підкаталог у списку `ignorePaths`. Якщо так, пропускає обхід цього підкаталогу та його вмісту.
+    2.2. Якщо підкаталог не в списку `ignorePaths`, обробляє вміст підкаталогу:
+    2.2.1. Для кожного файлу в підкаталозі, викликає функцію `onFile` з шляхом до файлу.
+    2.2.2. Для кожного підкаталогу в підкаталозі, рекурсивно викликає функцію `walkDir` для обходу цього підкаталогу. Під час рекурсивного виклику, також перевіряє, чи є підкаталог у списку `ignorePaths`.
+3.  Не обробляє каталоги `node_modules`, `.git`, `dist`, `coverage`, `.turbo` та `.next`.
+4.  Якщо при спробі `readdir` для каталогу виникає помилка, обхід цього каталогу припиняється.
+5.  Обхід завершується, коли всі підкаталоги та файли в заданому дереві були оброблені.
+
+## Публічний API
+
+- walkDir — Обходить каталог рекурсивно, ігноруючи вказані шляхи.
+
+## Гарантії поведінки
+
+- Функція рекурсивно обходить дерево каталогів, починаючи з заданого кореня.
+- Для кожного звичайного файлу викликається переданий callback.
+- Не обходить каталоги `node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next`.
+- Може пропустити каталоги, вказані в `ignorePaths`.
+- У разі невдачі `readdir` для каталогу, функція тихо виходить без викидання помилок.
+- Функція не викидає винятки назовні.
+- У разі невдачі повертає `false` або `null`.
+- Не використовує кешування.

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

@@ -0,0 +1,25 @@
+# with-lock.mjs
+
+## Огляд
+
+Цей файл реалізує механізм захисту від одночасного виконання критичних операцій, забезпечуючи атомарний lock та дедуплікацію даних для інтенсивних команд. Він використовується для запобігання конфліктів при одночасному виконанні операцій, які можуть призвести до пошкодження даних або непередбачуваних результатів. Механізм гарантує, що кожен прогін операцій виконується без повторень та з атомарним lock.
+
+## Поведінка
+
+- `shouldDedup`: Перевіряє, чи можна повторно використати кешований результат, враховуючи код виходу, відбитковий дерева та час завершення.
+- `withLock`: Встановлює lock-директорію, запускає вказану функцію, кешує результат та повторно використовує його, якщо можливо, з використанням дедуплікації за відбитком.
+
+## Публічний API
+
+- shouldDedup — Перевіряє, чи можна використовувати попередньо обчислену відповідь для уникнення повторних обчислень.
+- withLock — Забезпечує унікальність виконання важкої операції за допомогою блокування та перевірки на основі відбитків.
+
+## Гарантії поведінки
+
+- **Атомарність:** Операції lock та dedup виконуються як атомарні дії.
+- **Захист від помилок:** У разі виникнення помилки, функція повертає `false` та `null`.
+- **Детектування неактивного PID:** Перевіряється, чи процес, що утримує lock, все ще активний.
+- **Дедуплікація з обмеженням часу:** Проводиться дедуплікація за допомогою SHA256 з обмеженням часу (TTL).
+- **Кешування:** Результати прогону кешуються для прискорення наступних проходів.
+- **Відсутність винятків:** Функції не викликають винятків.
+- **Створення директорій:** Використовується `mkdirSync` для створення директорій.

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

@@ -0,0 +1,27 @@
+# worktree-fingerprint.mjs
+
+## Огляд
+
+Файл надає унікальний відбиток робочої директорії. Цей відбиток використовується для ідентифікації та порівняння робочих директорій, забезпечуючи їх унікальність у системі. Він слугує базовим інструментом для відстеження та управління версіями.
+
+## Поведінка
+
+1.  Отримує поточний SHA256 хеш коміту, який знаходиться в гілці HEAD.
+2.  Отримує текст зміни між комітом HEAD та робочим каталогом.
+3.  Отримує список не відстежених файлів у робочому каталозі, не включаючи стандартні файли, що ігноруються.
+4.  Для кожного не відстеженого файлу отримує його SHA256 хеш.
+5.  Об'єднує SHA256 хеш коміту, текст зміни та пари "файл:хеш" не відстежених файлів, розділяючи їх новими рядками.
+6.  Обчислює SHA256 хеш отриманого текстового рядка.
+7.  Повертає отриманий SHA256 хеш у форматі 64-значної шестнадцяткової строки.
+8.  Якщо виникає помилка під час виконання будь-якої з операцій, повертає `null`.
+
+## Публічний API
+
+worktreeFingerprint — генерує унікальний відбиток поточного стану репозиторію Git.
+
+## Гарантії поведінки
+
+- Функція повертає `true`, якщо відбиток дерева робіт успішно обчислено.
+- Функція повертає `null`, якщо обчислення відбитка дерева робіт не вдалося.
+- Функція не викликає винятків.
+- Функція не використовує кеш.

package/skills/docgen/js/docgen-batch.mjs

@@ -0,0 +1,95 @@
+/**
+ * Batch docgen для відсутніх файлів проєкту.
+ * sym < 4 → gemma3:4b orchestrated (local)
+ * sym ≥ 4 → Claude Sonnet (cloud, via generateDoc pre-routing)
+ */
+import { readFileSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { generateDoc } from './docgen-gen.mjs'
+import { extractFacts } from './docgen-extract.mjs'
+import { execSync } from 'node:child_process'
+
+const ROOT = resolve(fileURLToPath(import.meta.url), '../../../../..')
+
+// 1. Отримати список відсутніх файлів
+const scanOut = execSync('node npm/bin/n-cursor.js docgen scan', { cwd: ROOT, encoding: 'utf8' })
+const allFiles = JSON.parse(scanOut)
+const missing = allFiles.filter(x => !x.exists)
+
+console.log(`\n📋 Файлів для генерації: ${missing.length}`)
+
+// 2. Розкласти по тирах
+const local = [],
+  cloud = []
+for (const f of missing) {
+  try {
+    const src = readFileSync(join(ROOT, f.sourcePath), 'utf8')
+    const facts = extractFacts(src, join(ROOT, f.sourcePath))
+    const sym = (facts.internalSymbols ?? []).length
+    if (sym >= 4) cloud.push({ ...f, sym })
+    else local.push({ ...f, sym })
+  } catch {
+    local.push({ ...f, sym: 0 })
+  }
+}
+
+console.log(`  Local (sym<4): ${local.length}`)
+console.log(`  Cloud (sym≥4): ${cloud.length}`)
+
+const stats = { ok: 0, err: 0, localOk: 0, cloudOk: 0, errors: [] }
+
+// 3. Cloud файли (sym≥4) — generateDoc auto-routes до Claude
+console.log('\n☁️  Cloud tier...')
+for (const f of cloud) {
+  const t0 = Date.now()
+  try {
+    const result = await generateDoc(join(ROOT, f.sourcePath), { symThreshold: 4 })
+    const docAbs = join(ROOT, f.docPath)
+    mkdirSync(dirname(docAbs), { recursive: true })
+    writeFileSync(docAbs, result.md)
+    stats.ok++
+    stats.cloudOk++
+    console.log(`  ✓ ${f.sourcePath} (sym=${f.sym}, ${Math.round((Date.now() - t0) / 1000)}s)`)
+  } catch (e) {
+    stats.err++
+    stats.errors.push(f.sourcePath)
+    console.error(`  ✗ ${f.sourcePath}: ${e.message}`)
+  }
+}
+
+// 4. Local файли (sym<4) — gemma3:4b orchestrated
+console.log('\n💻 Local tier...')
+let done = 0
+for (const f of local) {
+  done++
+  const t0 = Date.now()
+  const pct = Math.round((done / local.length) * 100)
+  process.stdout.write(`  [${done}/${local.length} ${pct}%] ${f.sourcePath} ... `)
+  try {
+    const result = await generateDoc(join(ROOT, f.sourcePath), {
+      mode: 'orchestrated',
+      symThreshold: 999 // force local
+    })
+    const docAbs = join(ROOT, f.docPath)
+    mkdirSync(dirname(docAbs), { recursive: true })
+    writeFileSync(docAbs, result.md)
+    stats.ok++
+    stats.localOk++
+    process.stdout.write(`✓ ${Math.round((Date.now() - t0) / 1000)}s score=${result.score ?? '?'}\n`)
+  } catch (e) {
+    stats.err++
+    stats.errors.push(f.sourcePath)
+    process.stdout.write(`✗ ${e.message}\n`)
+  }
+}
+
+// 5. Підсумок
+console.log(`\n${'─'.repeat(50)}`)
+console.log(`✓ OK: ${stats.ok}  ✗ Err: ${stats.err}`)
+console.log(`  💻 Local (gemma3:4b): ${stats.localOk} файлів`)
+console.log(`  ☁️  Cloud (Claude/pi): ${stats.cloudOk} файлів`)
+if (stats.errors.length > 0) {
+  console.log('Помилки:')
+  stats.errors.forEach(e => console.log(`  - ${e}`))
+}

package/skills/docgen/js/docgen-extract.mjs

@@ -1,16 +1,22 @@
-/**
- * Stage 0 docgen-конвеєра: детермінована екстракція «факт-листа» з коду (0 токенів LLM).
- *
- * Ідея: винести з-під локальної моделі все, що вона псує (імена експортів, stdlib-vs-internal,
- * крайові деталі поведінки), і віддати їй лише перефразування вже відомих фактів. Тут — суто
- * парсинг JS/MJS регулярками: жодних мереж, LLM чи запису.
- *
- * Повертає об'єкт-факт-лист, який Stage 1 (docgen-prompts) перетворює на точкові промпти.
- */
+/** @see ./docs/docgen-extract.md */
 
 const BUILTIN_MODULES = new Set([
-  'fs', 'path', 'crypto', 'os', 'util', 'stream', 'events', 'http', 'https',
-  'url', 'child_process', 'process', 'assert', 'buffer', 'zlib', 'readline'
+  'fs',
+  'path',
+  'crypto',
+  'os',
+  'util',
+  'stream',
+  'events',
+  'http',
+  'https',
+  'url',
+  'child_process',
+  'process',
+  'assert',
+  'buffer',
+  'zlib',
+  'readline'
 ])
 
 /** Прибирає `/** *​/`-обрамлення й `*`-префікси, повертає чистий текст рядками. */
@@ -40,7 +46,10 @@ function parseJsDoc(raw) {
       params.push({ name: pm[1], desc: desc === 'опис.' ? '' : desc })
       continue
     }
-    if (rm) { ret = rm[1].trim(); continue }
+    if (rm) {
+      ret = rm[1].trim()
+      continue
+    }
     if (l.startsWith('@')) continue
     descLines.push(l)
   }
@@ -81,7 +90,9 @@ function extractExports(src) {
 
 /** Імпорти, класифіковані на stdlib / npm / internal. */
 function extractImports(src) {
-  const stdlib = new Set(), npm = new Set(), internal = new Set()
+  const stdlib = new Set(),
+    npm = new Set(),
+    internal = new Set()
   const re = /^import\s+[\s\S]*?from\s+['"]([^'"]+)['"]/gm
   let m
   while ((m = re.exec(src))) {
@@ -100,10 +111,11 @@ function extractInternalSymbols(src) {
   let m
   while ((m = re.exec(src))) {
     if (m[1]) out.add(m[1].trim())
-    if (m[2]) for (const n of m[2].split(',')) {
-      const name = n.replace(/\s+as\s+.*/, '').trim()
-      if (name) out.add(name)
-    }
+    if (m[2])
+      for (const n of m[2].split(',')) {
+        const name = n.replace(/\s+as\s+.*/, '').trim()
+        if (name) out.add(name)
+      }
   }
   return [...out]
 }
@@ -152,7 +164,10 @@ import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { readFileSync } from 'node:fs'
 if (isRunAsCli(import.meta.url)) {
   const file = process.argv[2]
-  if (!file) { console.error('Usage: node docgen-extract.mjs <file>'); process.exit(1) }
+  if (!file) {
+    console.error('Usage: node docgen-extract.mjs <file>')
+    process.exit(1)
+  }
   const facts = extractFacts(readFileSync(file, 'utf8'), file)
   console.log(JSON.stringify(facts, null, 2))
 }