@nitra/cursor 3.27.0 → 3.28.0

package/scripts/lib/docs/template.md

@@ -0,0 +1,40 @@
+# template.mjs
+
+## Огляд
+
+Файл обробляє шаблони для певних напрямків, збираючи їх у єдину структуру, яка індексується за назвою цільового файлу. Він повертає найбільш відповідний шаблон з `snippet/`, `deny/` або `contains/`, розпізнаний за розширенням, для кожного цільового файлу. Це забезпечує можливість динамічної генерації контенту на основі шаблонів, визначених для різних областей застосунку.
+
+## Поведінка
+
+- `parseByExt`: Парсує файл на основі його розширення, повертаючи JS об'єкт для структурованих форматів або рядок для тексту.
+- `checkSnippet`: Перевіряє, чи всі значення у фрагменті збігаються з відповідними шляхами у фактичному значенні, з урахуванням масивів.
+- `checkDeny`: Перевіряє, чи містить фактичне значення будь-який шлях, вказаний у дереві заборони.
+- `checkContains`: Перевіряє, чи містить фактичне значення будь-який шлях, вказаний у дереві обов'язкових підрядків.
+- `checkTextSubset`: Перевіряє, чи містять всі рядки у шаблоні фактичне значення.
+- `loadTemplate`: Зчитує файли з каталогу шаблонів, парсує їх і повертає об'єкт, індексований за назвою цілі.
+- `resolveConcernTemplateData`: Визначає відповідний шаблон для заданого «concern», використовуючи `target.json`.
+
+## Публічний API
+
+- parseByExt: Розбирає вміст файлу за розширенням, повертаючи JS об'єкт для структурованих форматів або рядок для тексту.
+- checkSnippet: Перевіряє відповідність фрагмента фактичному контенту: кожна гілка фрагмента повинна відповідати гілці в фактичному контенті. Масиви в фрагменті повинні бути присутніми у фактичному масиві. Повертає масив повідомлень про порушення.
+- checkDeny: Проходить по дереву заборон, повертаючи повідомлення про порушення для будь-якої гілки, яка існує в фактичному контенті, з причиною у вигляді рядка з листом заборони.
+- checkContains: Перевіряє, чи містять всі рядки з масиву `contains` в якості підрядків відповідні гілки в `actual` (рядок листка).
+- checkTextSubset: Перевіряє текстові цілі (наприклад, .stylelintignore): кожна не порожня, не коментарна лінія в шаблоні повинна з'являтися (з видаленими пробілами) у фактичному контенті.
+- loadTemplate: Завантажує шаблон.
+- resolveConcernTemplateData: Визначає, який шаблон [`<ціль>`](target) передати для заданого контексту, на основі файлу `target.json`. Для цілей `single` - використову
+
+## Гарантії поведінки
+
+- Файл читає шаблон для заданої області відповідальності та повертає об'єднану структуру, індексовану за основою імені файлу цілі.
+- Для кожної цілі повертається один із файлів snippet/, deny/ або contains/, розібраний у нативному форматі за розширенням.
+- Функція `parseByExt` повертає об'єднану структуру.
+- Функція `checkSnippet` повертає результат перевірки snippet/.
+- Функція `checkDeny` повертає результат перевірки deny/.
+- Функція `checkContains` повертає результат перевірки contains/.
+- Функція `checkTextSubset` повертає результат перевірки підмножини тексту.
+- Функція `loadTemplate` завантажує шаблон.
+- Функція `resolveConcernTemplateData` розв'язує дані шаблону для заданої області відповідальності.
+- Шляхи `node_modules` ігноруються.
+- Файл є read-only.
+- Кешування відсутнє.

package/scripts/lib/docs/timing-summary.md

@@ -0,0 +1,24 @@
+# timing-summary.mjs
+
+## Огляд
+
+Цей файл генерує табличне резюме часу виконання для команд `fix` та `lint`, які використовуються в orchestrator. Він підсумовує час виконання окремих правил та скриптів linting, надаючи інформацію для аналізу продуктивності. Результат представлений у вигляді рядка, який можна вивести для відображення користувачеві.
+
+## Поведінка
+
+formatDurationMs: Перетворює мілісекунди на рядок у форматі `<ціла>.<десята>s`.
+formatTimingSummary: Формує таблицю-резюме часу виконання з масиву записів, виводячи їх у текстовому форматі.
+
+## Публічний API
+
+- formatDurationMs — Форматує значення тривалості в форматі `<сек>.<десята>с`. Округлення виконується вниз (floor), щоб забезпечити консистентність результатів незалежно від платформи.
+- formatTimingSummary — Створює багаторядковий текст у форматі таблиці-резюме для виведення в консоль (stdout).
+
+## Гарантії поведінки
+
+❌ Якщо `ok` дорівнює `false`, повертає `null`.
+❌ Якщо час виконання перевищує 5 секунд, повертає `null`.
+Повертає рядок, що містить таблицю з часом виконання.
+Час виконання виражається у форматі `<ціла>.<десята>s`.
+Повертає рядок з символом `\n` в кінці.
+Не використовує кешування.

package/scripts/lib/docs/workspaces.md

@@ -0,0 +1,30 @@
+# workspaces.mjs
+
+## Огляд
+
+Цей файл визначає список кореневих каталогів пакетів у монорепо, використовуючи конфігурацію `workspaces` з `package.json`. Він використовується скриптами перевірки монорепо для ідентифікації всіх проектів, які потрібно перевірити. Результат повертається для подальшого використання в процесах перевірки та аналізу.
+
+## Поведінка
+
+`isIgnoredWorkspaceRoot`: Перевіряє, чи слід ігнорувати каталог як корінь воркспейсу.
+`normalizeWorkspacePattern`: Нормалізує воркспейс-патерн до POSIX-формату, видаляючи хвостові `/`.
+`normalizeWorkspacePatterns`: Перетворює значення `workspaces` в масив воркспейс-патернів.
+`getMonorepoPackageRootDirs`: Збирає список коренів пакетів воркспейсу з `package.json`.
+`WORKSPACE_GLOB_IGNORE`: Ігнорує каталоги `node_modules`, `.git`, `.venv` та `venv`.
+
+## Публічний API
+
+- WORKSPACE_GLOB_IGNORE — Ігнорує шаблони workspace, що містять `*`, як визначено в `rules/changelog/js/consistency/package-manifest.mjs`.
+- isIgnoredWorkspaceRoot — Визначає, чи слід виключити каталог з списку коренів workspace (не враховує `.`).
+- normalizeWorkspacePatterns — Перетворює поле `workspaces` з `package.json` на масив шляхів або glob-шаблонів.
+- getMonorepoPackageRootDirs — Повертає список кореневих каталогів пакетів, включаючи корінь репозиторію та всі пакети, визначені в `workspaces`.
+
+## Гарантії поведінки
+
+- Повертає порожній список каталогів, якщо не знайдено жодного `package.json` у кореневому каталозі або в каталогах, що відповідають `WORKSPACE_GLOB_IGNORE`.
+- Повертає `false` якщо не вдалося прочитати `package.json` у будь-якому з каталогів.
+- Не включає в список каталог `node_modules`.
+- Не включає в список каталог `.git`.
+- Повертає лише кореневі каталоги пакетів монорепо, визначені в `package.json` файлах.
+- Повертає відносну шляху до кореневого каталогу пакету.
+- Не використовує кешування.

package/scripts/lib/docs/worktree-notice.md

@@ -0,0 +1,27 @@
+# worktree-notice.mjs
+
+## Огляд
+
+Цей файл вбудовує інструкції щодо використання git-worktree, коли `meta.json.worktree` встановлено в `true`. Він забезпечує паралельне виконання скілу лише в окремому git-worktree, запобігаючи потенційним проблемам з паралелізмом. Цей механізм дозволяє уникнути гонки з CDN та забезпечує надійний запуск скілу з локальною копією CLI.
+
+## Поведінка
+
+WORKTREE_START: вставляє маркер початку worktree-блоку.
+WORKTREE_END: вставляє маркер кінця worktree-блоку.
+injectWorktreeNotice: вставляє або видаляє worktree-блок у `SKILL.md` на основі значення `meta.json.worktree`. Якщо `meta.json.worktree` `true`, вставляє блок; інакше видаляє. Якщо блок вже існує, замінює його; якщо ні — додає. Враховує наявність YAML-frontmatter та вставляє блок після нього. Використовує транслітерацію для створення суфікса гілки. Реалізує retry-обгортку для `npx` з обмеженням часу та інтервалом для перевірки.
+
+## Публічний API
+
+WORKTREE_START — Початок блоку worktree.
+WORKTREE_END — Кінець блоку worktree.
+injectWorktreeNotice — Змінює вміст SKILL.md, додаючи, оновлюючи або видаляючи worktree-блок.
+
+## Гарантії поведінки
+
+Якщо `meta.json.worktree === true`, то скіл виконується в окремому git-worktree.
+Скіл не паралелізується.
+Після створення worktree виконується `bun install` у цьому worktree.
+Виконується shell-обгортка `n_cursor_npx` навколо `npx` для bootstrap-виклику.
+Обгортка `n_cursor_npx` виконує retry на транзитні помилки реєстру/мережі (інтервал 30с, дефолт 5 хв, `N_CURSOR_NPX_RETRY_MAX_MIN`, ceiling 10 хв).
+При виникненні nonzero CLI повертається одразу.
+Команди, що вимагають command substitution, виконуються після створення worktree.

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`, якщо обчислення відбитка дерева робіт не вдалося.
+- Функція не викликає винятків.
+- Функція не використовує кеш.